Build Group Messaging Apps with the First and Only Group Messaging API

Note: The demo here assumes at least a basic knowledge of Node.js and Express.


Application developers all over the world have integrated helpful bots and scripts into chat apps. Any modern chat system allows relatively quick Integration through their API; slack, messenger, WhatsApp, etc. However, there is one channel, with the greatest number of users, no one has been able to reach: simple SMS. That is until now.

Bandwidth's group messaging API allows developers to integrate directly with users' group message chats by simply adding a new phone number to the chat. Once the phone number has been added to the group chat, that's when the magic happens. The Bandwidth messaging API will send Webhooks to the configured server any time a message is sent to the group. The Webhook contains the text of the message as well as the participating members.

Developers can then tie anything they'd like from the API ecosystem into the group chat. Want to provide contextual information from Yelp's API on finding a great place to grab brunch? Done. Notice your users are chatting about seeing the next blockbuster film? Reach out to Fandago's API to provide some movie times, all within the group chat that's already taking place. Really, the possible combinations of APIs are mind-blowing.


To demonstrate what this could look like, let's walk through a simple Node.js application that serves up a phone number that can be added to any group messaging thread to serve up awesome gifs on command. Let's add @gif to a group message thread!

This demo will use the

The application that we build will implement the following basic workflow:

  1. Receive incoming message event
  2. Ensure message.direction == 'in'. We're ignoring delivery notifications for now
  3. Check that the text string starts with @gif. If not, ignore the message.
  4. Extract the string after the @gif.
  5. Search GIPHY for Developers for the phrase
  6. Pick a random GIF from the response
  7. Send the GIF to the group!

Search GIPHY

The GIPHY API returns a list of GIF responses that contain various sizes and metadata about the image. Since we're going to attach this as an MMS, we need to search for any version of the GIF that is less than 1.5MB.

Sample GIPHY Response

{ "type": "gif", "id": "...", "...": "...", "images": { "fixed_height_still": { " URL": " HTTPS:\/\/\/.../cid={gifID}", "width": "358", "height": "200", "size": "50867" }, "...": { "url": "https:\/\/\/.../cid={gifID}", "width": "499", "height": "279", "size": "108964" } } }

Sample Async Node.js Function to search for GIF

/** * Search GIPHY for random GIF < maxGifSize * @returns {STRING} Returns GIF URL **/ const getGifUrl = async (query) => { try { const gifs = await; // Search for random GIF < maxGifSize const gifUrl = searchGifResponse(gifs); return gifUrl; } catch (e) { debug(e); return false; } };

Attach and Send the GIF

Bandwidth's API takes a JSON request with a few parameters to send a group message. The most common parameters would include an array of phone numbers and an array of mediaURLs to attach to the message.

Sample HTTP Request to Group Message API

POST{userId}/messages HTTP/1.1 Content-Type: application/json; charset=utf-8 Authorization: {apiToken:apiSecret} { "to" : [ "+12345678902", "+12345678903" ], "from" : "+12345678901", "text" : "GIF for: crazy cat", "applicationId" : "93de2206-9669-4e07-948d-329f4b722ee2", "media" : [ "{gifID}" ] }

Sample Express Middleware to build a Group Message.

/** * Middleware the process the incoming text and look for GIF. * Once GIF is found, send it back to the group. * If no GIF is found, send a message letting the group know **/ module.exports.processMessage = async (req, res, next) => { // Callbacks are arrays of 1, take first one const message = req.body[0]; // Extract anything after `@gif ` const query = extractQuery(message.message.text); // Search giphy for const mediaUrl = await getGifUrl(query); // Build Message to send const outMessage = { to : buildToArray(message), from :, applicationId : message.message.applicationId }; if (!mediaUrl) { outMessage.text = ` Unable to find gif for ${query}`; } else { outMessage.text = `GIF for: ${query}`; = [mediaUrl]; } res.locals.outMessage = outMessage; next(); }; /** * Middleware to actually send the Message in res.locals.outMessage; **/ module.exports.sendMessage = async (req, res) => { const message = res.locals.outMessage; // Make API Request to send message const messageResponse = await sendMessage(message); debug(messageResponse); return; }

All together

You can see the full application at Github and 1-click deploy with Heroku once you have your API Credentials.

Group MMS Video Deploy


In Review

There are powerful applications specifically in the consumer Customer Relationship Management (CRM) space that are adding even more value with group media messaging. Pick a 'vertical' and most likely there are multiple CRM offerings just for that specific use-case. These CRM applications provide value for their users by tracking all interactions with slick dashboards, providing customer insight by linking together social profiles and act as a one-stop shop for all customer communications. Win a deal or lose a deal? Run some AI and analytics for all communications to learn what worked or what didn't. Need to reach out to an existing client? Click the 'text' button and fill out your message to have your text sent via your business line. The applications that are enabled by tracking all communications from a single-source-of-truth are continuously growing.

Take real-estate CRM software for example. Realtors love managing their relations from a single interface and dashboard. One of the smaller annoyances is coordinating with all the family members involved with the purchase decision. A typical flow would be to reach out to the main point of contact and propose a 'showing' time. That point of contact then 'gathers' everyone else to determine a time. A realtor could use their personal cell phone to group message the entire group, however, they would lose the ability to track the conversation and could be messaging the point-of-contact from a new phone number. Instead, the CRM application could leverage Bandwidth's new group messaging API to provide the realtor to message the entire group from within the app with all the advantages.

And that's just the beginning! There are more and more companies leveraging Bandwidth's APIs for new use-cases we haven't thought of. Ready to get started on your idea? Request access to the Bandwidth Group Messaging API here!

Be sure to read the next Messaging article: Blockstream Launches Beta Version of Satellite API for Data Broadcast