Send batch messages

Send batch messages

The send batch messages endpoint allows sending a batch up to 100 messages to a channel. The messages are accepted for validation and processed asynchronously. Messages that fail validation are rejected, and the failure is attached to the message. The response will return a batch ID which can be used to retrieve the messages that were in the batch.

POSThttps://api.bird.com/workspaces/{workspaceId}/channels/{channelId}/batch/messages

Path parameters

workspaceId*string (uuid)

The ID of the workspace

channelId*string (uuid)

The ID for a channel

Body

application/json

messageRequestsarray of Channels_CreateMessage (all of)

Response

202400404422

Messages were accepted to be validated asynchronously and then processed.

Body

application/json

id*string (uuid)

The ID of the batch.

Example: "a1405560-c8d3-4b1a-877d-3f449ad95352"

messages*array of BatchMessage

Request

JavaScriptCurlPython

const response = await fetch('https://api.bird.com/workspaces/{workspaceId}/channels/{channelId}/batch/messages', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

202400404422

{
  "id": "a1405560-c8d3-4b1a-877d-3f449ad95352",
  "messages": [
    {
      "id": "a1405560-c8d3-4b1a-877d-3f449ad95352"
    }
  ]
}

Examples

Let's establish some of our data that will be used in the following examples:

• Workspace ID: a1405560-c8d3-4b1a-877d-3f449ad95352

• AccessKey: abcd

• Channel ID: a1405560-c8d3-4b1a-877d-3f449ad95352

Send batch of messages

In this example, we're sending multiple SMS messages to different receivers using variations of content.

Request

curl -X POST "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/channels/a1405560-c8d3-4b1a-877d-3f449ad95352/batch/messages" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
    "messageRequests": [
        {
            "receiver": {
                "contacts": [
                    {
                        "identifierValue": "[e-mail]"
                    }
                ]
            },
            "body": {
                "type": "text",
                "text": {
                    "text": "Hey, I am a simple text message"
                }
            }
        },
        {
            "receiver": {
                "contacts": [
                    {
                        "identifierValue": "[e-mail]"
                    }
                ]
            },
            "template": {
                "projectId": "4b7e08a9-5d0e-4e56-aaf1-cd0bfa29d431",
                "version": "fe72e43f-340e-4d41-9a9e-a136278ebb04",
                "locale": "en"
            }
        },
        {
            "receiver": {
                "contacts": [
                    {
                        "identifierValue": "[e-mail]"
                    }
                ]
            },
            "body": {
                "type": "text",
                "text": {
                    "text": "Hey, I am a scheduled message"
                }
            },
            "scheduledFor": "2024-11-26T15:00:00.000Z"
        }
    ]
}'

Response (200 - OK)

{
    "id": "70cc4cfa-0756-4ca7-8566-c8a83ee92af3",
    "messages": [
        {
            "id": "71d1c562-c8c8-4f03-89ff-2ed0026ea1ea"
        },
        {
            "id": "e75e3dd7-9429-4d9b-a006-c2eba19a1baa"
        },
        {
            "id": "3e7d1712-0fdb-476d-bf01-3d8ceb6a1d19"
        }
    ]
}

Batch messages can be monitored using Retrieving messages endpoints by providing the batchID returned in the response. This allows you to check if any messages within the batch failed. Messages with a rejected status will emit events, containing detailed failure codes, enabling you to identify and address issues efficiently. For more details on how to subscribe to these events, refer to the Notifications API documentation.