Receiving messages

Programmable Conversations allows you to receive messages from users over any supported communication platform.

A conversation is a thread of sent and received messages. In this Programmable Conversations Quickstart, you'll learn how to handle inbound messages and complete the circle of your conversation using cURL.

You have two ways of receiving messages:

• You can get real-time notifications pushed to your server through webhooks. Webhooks can be created and managed with the API.
• You can poll conversations and individual messages via the API.

Webhooks

Webhooks enable real-time notifications delivery of conversation events to endpoints on your server and you can use them to integrate more deeply with your preferred CRM or to build a bot. A webhook's configuration contains your URL and a list of events for which MessageBird should notify you.

When your webhook is triggered, you'll receive a JSON payload will be posted to the URL configured in your webhook object. For the message.created event, the payload looks similar to the following:

{
  "conversation": {
    "contactId": "73afe0acee2127fd3e7d9a7dc622826e",
    "createdDatetime": "2019-02-28T17:39:52Z",
    "id": "f1e812e9afd6a875d813d51f45823edd",
    "lastReceivedDatetime": "2019-03-01T10:40:02.880881081Z",
    "status": "active",
    "updatedDatetime": "2019-02-28T18:33:24.787229989Z"
  },
  "message": {
    "channelId": "2ceefea7c1b8c79673215c42c1a6b916",
    "content": {
      "text": "Testing webhook functionality."
    },
    "conversationId": "f1e812e9afd6a875d813d51f45823edd",
    "createdDatetime": "2019-03-01T10:40:02.880881081Z",
    "direction": "received",
    "id": "93a1f7ba935c4ee298cb5ef952052ea7",
    "status": "received",
    "type": "text",
    "updatedDatetime": "2019-03-01T10:40:02.88845145Z"
  },
  "type": "message.created"
}

As you can see, the payload contains information on the message. It's possible to create multiple webhooks with different URLs to subscribe to one or more events each.

Programmatically configure webhooks via the API

To create a webhook using the Programmable Conversations API simply copy the following code snippet to your IDE and replace YOUR-API-KEY with your API key, channelId to your Channel ID, and url to your publicly-accessible URL. Then, run the command in your terminal.

curl -X "POST" "https://conversations.messagebird.com/v1/webhooks" \
-H "Authorization: AccessKey YOUR-API-KEY" \
-H "Content-Type: application/json" \
--data '{
"events":["message.created", "message.updated"],
"channelId": "CHANNEL-ID",
"url":"https://your-domain.com/webhook"
}'

If the set up was correct, you'll receive an API response that contains “status” : “enabled”. If something went wrong, you’ll receive an error response from the MessageBird API. Don't worry, simply head over to the Conversations API Troubleshooting to understand the error.

If you have a local development server that can receive webhooks, you can generate a public URL with a tool like ngrok.

Programmable Conversations API Reference provides full details on how to programmatically configure and manage webhooks via the API,, and the expected responses for each API request.

Retrieving conversation history

Every message sent or received through Programmable Conversations is available via the API in its conversation object as long as they haven’t been deleted from the system.

To access all conversations, you make the following GET request by replacing your credentials as usual:

curl "https://conversations.messagebird.com/v1/conversations" \
-H "Authorization: AccessKey YOUR-API-KEY"

To make it easier to read the API response, install jq on your computer and add

| jq

to the end of the command to pretty-print JSON.

To access a specific conversation’s history with all messages, make the following GET request, replacing CONVERSATION-ID with the ID of the conversation that you retrieved in the previous request:

curl "https://conversations.messagebird.com/v1/conversations/CONVERSATION-ID/messages" \
-H "Authorization: AccessKey YOUR-API-KEY"

You can view the full example responses in the Programmable Conversations API Reference.

Nice work! 🎉 You can now programmatically receive messages with the MessageBird Programmable Conversations.