Programmatically Handle Inbound Messages

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.

You have two ways of handling inbound messages:

  • Through webhooks, you can get real-time notifications pushed to your server. You can create and manage webhooks with the API.
  • You can poll conversations and individual messages from the API.


Webhooks enable real-time notifications delivery of conversation events to endpoints on your server. A webhook's configuration contains your URL and a list of events for which MessageBird should notify you. It's possible to create multiple webhooks with different URLs to subscribe to one or more events each.

When your webhook is triggered, youll receive a JSON payload. For the

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"

Programmatically configure webhooks via the API

To create a webhook using the Programmable Conversations API, you can copy the following code snippet to your IDE.


with your API key, set
to your Channel ID and a publicly-accessible URL as
. If you have a local development server that can receive webhooks, you can generate a public URL with a tool like ngrok. If you don't have any server-side implementation yet and still want to test this functionality, you can create a webhook with tools like Hookeepr.

Then, run the command in your terminal:

$ curl -X "POST" "" \
-H "Authorization: AccessKey YOUR-API-KEY" \
-H "Content-Type: application/json" \
--data '{
"events":["message.created", "message.updated"],
"channelId": "CHANNEL-ID",

Confirm that the API response contains

“status” : “enabled”
to indicate that your webhook was enabled correctly.

Notification icon

Programmable Conversations API Reference provides full details on how to programmatically configure and manage webhooks via the API.

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 "" \
-H "Authorization: AccessKey YOUR-API-KEY"
Notification icon

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

with the ID of the conversation that you retrieved in the previous request:

$ curl "" \
-H "Authorization: AccessKey YOUR-API-KEY"

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

Congrats! You can now programmatically handle to inbound messages with Programmable Conversations.

Next Steps

You may now want to check out these resources:


We’re always happy to help with code or other questions you might have! Search our API Reference, check the Developer tutorials or contact support.

Cookie Settings