Sending SMS messages
Last updated
Was this helpful?
Last updated
Was this helpful?
In order to send a message, you must have an active SMS channel and perform a HTTP request to the following endpoint with a valid access key
When sending outbound messages as well as setting the receiver information you must set message body field in all cases except for sending a message template when you must only set the template field
Body
{
"receiver": {
"contacts": [
{
"identifierKey": "phonenumber",
"identifierValue": "+31612345678"
}
]
},
"body": {...}
}
Template
{
"receiver": {
"contacts": [
{
"identifierKey": "phonenumber",
"identifierValue": "+31612345678"
}
]
},
"template": {...}
}
All SMS channels support sending basic text based messages using SMS. The example below must be set in the message body field
{
"receiver": {
"contacts": [
{
"identifierValue": "+31612345678"
}
]
},
"body": {...}
}
To send an SMS text message set the message body as follows:
{
"type": "text",
"text": {
"text": "Single text message"
}
}
SMS channels that are installed with MMS capable numbers (currently numbers purchased for the United States and Canada) also support media messaging. You can also verify if the channel is MMS capable via the API as described here.
Single image message with text and title
When sending multiple image messages it is possible to send up to an array of 10 media URLs.
The examples below must be set in the message template field
{
"receiver": {
"contacts": [
{
"identifierValue": "+31612345678"
}
]
},
"template": {...}
}
Text templates will be sent as SMS messages and are compatible with all SMS channels
Using it is possible to create text and media templates that can quickly be reused to send to contacts. Templates must be active before they are used.
{
"type": "image",
"image": {
"images": [
{
"mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FRPPgQAGyZE7rvIh3WM2Z%2Fimage2.avif?alt=media"
}
]
}
}
{
"type": "image",
"image": {
"images": [
{
"mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FRPPgQAGyZE7rvIh3WM2Z%2Fimage2.avif?alt=media"
}
],
"text": "Single image message"
}
}
{
"type": "image",
"image": {
"images": [
{
"mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FRPPgQAGyZE7rvIh3WM2Z%2Fimage2.avif?alt=media"
}
],
"text": "Single image message",
"metadata": {
"subject": "Message subject"
}
}
}
{
"type": "image",
"image": {
"images": [
{
"mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FRPPgQAGyZE7rvIh3WM2Z%2Fimage2.avif?alt=media"
},
{
"mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FrEM9zztd8SEiJS6RQuR3%2Fimage.png?alt=media"
}
]
}
}
{
"type": "image",
"image": {
"images": [
{
"mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FRPPgQAGyZE7rvIh3WM2Z%2Fimage2.avif?alt=media"
},
{
"mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FrEM9zztd8SEiJS6RQuR3%2Fimage.png?alt=media"
}
],
"text": "Multiple images message"
}
}
{
"type": "image",
"image": {
"images": [
{
"mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FRPPgQAGyZE7rvIh3WM2Z%2Fimage2.avif?alt=media"
},
{
"mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FrEM9zztd8SEiJS6RQuR3%2Fimage.png?alt=media"
}
],
"text": "Multiple images message",
"metadata": {
"subject": "Message subject"
}
}
}
{
"type": "file",
"file": {
"files": [
{
"mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FtXMQ4lIinia9ehf4EpC4%2Fvideo.mp4?alt=media",
"contentType": "video/mp4"
}
]
}
}
{
"type": "file",
"file": {
"files": [
{
"mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FtXMQ4lIinia9ehf4EpC4%2Fvideo.mp4?alt=media",
"contentType": "video/mp4"
}
],
"text": "Single file message"
}
}
{
"type": "file",
"file": {
"files": [
{
"mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FtXMQ4lIinia9ehf4EpC4%2Fvideo.mp4?alt=media",
"contentType": "video/mp4"
}
],
"text": "Single file message",
"metadata": {
"subject": "Message subject"
}
}
}
{
"type": "file",
"file": {
"files": [
{
"mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FtXMQ4lIinia9ehf4EpC4%2Fvideo.mp4?alt=media",
"contentType": "video/mp4"
},
{
"mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FbgnxOoaF4aHSHUzMFCna%2Faudio.mp3?alt=media",
"contentType": "audio/mpeg"
}
],
"text": "Multiple files message"
}
}
{
"type": "file",
"file": {
"files": [
{
"mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FtXMQ4lIinia9ehf4EpC4%2Fvideo.mp4?alt=media",
"contentType": "video/mp4"
},
{
"mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FbgnxOoaF4aHSHUzMFCna%2Faudio.mp3?alt=media",
"contentType": "audio/mpeg"
}
],
"text": "Multiple files message"
}
}
{
"type": "file",
"file": {
"files": [
{
"mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FtXMQ4lIinia9ehf4EpC4%2Fvideo.mp4?alt=media",
"contentType": "video/mp4"
},
{
"mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FbgnxOoaF4aHSHUzMFCna%2Faudio.mp3?alt=media",
"contentType": "audio/mpeg"
}
],
"text": "Multiple files message",
"metadata": {
"subject": "Message subject"
}
}
}
{ "projectId":"ce6a2fd6-b2fa-4f5a-a2cd-f3bd15883318",
"version":"latest",
"locale":"en",
"parameters":[
{
"type":"string",
"key":"name",
"value":"Robert"
}
]
}
Send a message to a channel
The ID of the workspace
The ID for a channel
curl -L \
--request POST \
--url '/workspaces/{workspaceId}/channels/{channelId}/messages' \
--header 'Authorization: Bearer jwt' \
--header 'Content-Type: application/json' \
--data '{
"sender": {
"connector": {
"identifierValue": "channels@bird.com",
"annotations": {
"name": "text"
}
}
},
"receiver": {
"contacts": [
{
"id": "a1405560-c8d3-4b1a-877d-3f449ad95352",
"identifierKey": "emailaddress",
"identifierValue": "channels@bird.com",
"type": "cc",
"identifiers": [
{
"identifierKey": "emailaddress",
"identifierValue": "channels@bird.com"
}
],
"platformAddress": "text",
"platformAddressSelector": "text"
}
]
},
"reference": "my-own-identifier",
"template": {
"name": "text",
"projectId": "a1405560-c8d3-4b1a-877d-3f449ad95352",
"version": "a1405560-c8d3-4b1a-877d-3f449ad95352",
"locale": "text",
"attachments": [
{
"mediaUrl": "https://example.com",
"filename": "text",
"inline": true
}
],
"shortLinks": {
"enabled": true,
"domain": "text"
},
"variables": {
"default": "text",
"ANY_ADDITIONAL_PROPERTY": "text"
},
"utmParameters": [
{
"key": "text",
"value": "text"
}
],
"parameters": [
{
"type": "string",
"key": "text",
"value": "text"
}
]
},
"meta": {
"extraInformation": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"referral": {
"source": "text",
"title": "text",
"text": "text",
"group": "text",
"metadata": {
"source_id": "text",
"source_url": "text",
"media_url": "text",
"tracking_id": "text"
}
},
"order": {
"products": [
{
"externalCatalogId": "text",
"externalProductId": "text",
"quantity": 1,
"price": {
"amount": 1,
"exponent": 1,
"currencyCode": "text"
}
}
]
},
"referredProduct": {
"externalCatalogId": "text",
"externalProductId": "text"
},
"email": {
"subject": "text",
"headers": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"from": {
"username": "text",
"displayName": "text"
}
},
"pushNotifications": {
"gatewayTypeOverride": "apns"
},
"navigatorId": "123e4567-e89b-12d3-a456-426614174000",
"navigatorMessageId": "123e4567-e89b-12d3-a456-426614174000",
"flow": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "text",
"stepId": "text",
"runId": "123e4567-e89b-12d3-a456-426614174000"
},
"journey": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "text",
"stepId": "text",
"runId": "123e4567-e89b-12d3-a456-426614174000"
},
"campaign": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "text"
}
},
"replyTo": {
"id": "text",
"order": 1,
"type": "message"
},
"body": {
"type": "text",
"text": {
"text": "text",
"attachments": [
{
"mediaUrl": "https://example.com",
"filename": "text",
"inline": true
}
],
"actions": [
{
"type": "link",
"link": {
"text": "text",
"url": "text"
}
}
],
"metadata": {
"subject": "text",
"headers": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"whatsapp": {
"previewUrl": true
},
"line": {
"emoji": {
"items": [
{
"index": 1,
"productId": "text",
"emojiId": "text"
}
]
}
},
"telegram": {
"parseMode": "Markdown"
}
}
}
},
"notification": {
"url": "text"
},
"capFrequency": true,
"enableLinkTracking": true,
"ignoreQuietHours": true,
"ignoreGlobalHoldout": true,
"tags": [
"text"
],
"shortLinks": {
"domain": "text"
},
"scheduledFor": "2025-03-28T19:11:21.734Z",
"validity": 1
}'
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"channelId": "123e4567-e89b-12d3-a456-426614174000",
"sender": {
"connector": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"identifierValue": "text",
"annotations": {
"name": "text"
},
"types": [
"text"
]
}
},
"receiver": {
"connector": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"identifierValue": "text",
"annotations": {
"name": "text"
},
"types": [
"text"
]
}
},
"meta": {
"extraInformation": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"referral": {
"source": "text",
"title": "text",
"text": "text",
"group": "text",
"metadata": {
"source_id": "text",
"source_url": "text",
"media_url": "text",
"tracking_id": "text"
}
},
"order": {
"products": [
{
"externalCatalogId": "text",
"externalProductId": "text",
"quantity": 1,
"price": {
"amount": 1,
"exponent": 1,
"currencyCode": "text"
}
}
]
},
"referredProduct": {
"externalCatalogId": "text",
"externalProductId": "text"
},
"email": {
"subject": "text",
"headers": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"from": {
"username": "text",
"displayName": "text"
}
},
"pushNotifications": {
"gatewayTypeOverride": "apns"
},
"navigatorId": "123e4567-e89b-12d3-a456-426614174000",
"navigatorMessageId": "123e4567-e89b-12d3-a456-426614174000",
"flow": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "text",
"stepId": "text",
"runId": "123e4567-e89b-12d3-a456-426614174000"
},
"journey": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "text",
"stepId": "text",
"runId": "123e4567-e89b-12d3-a456-426614174000"
},
"campaign": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "text"
}
},
"reference": "my-own-identifier",
"parts": [
{
"platformReference": "text"
}
],
"status": "accepted",
"reason": "text",
"direction": "incoming",
"origin": {
"type": "text",
"id": "text"
},
"replyTo": {
"id": "text",
"order": 1,
"type": "message"
},
"lastStatusAt": "2025-03-28T19:11:21.734Z",
"createdAt": "2025-03-28T19:11:21.734Z",
"updatedAt": "2025-03-28T19:11:21.734Z",
"details": "text",
"failure": {
"code": 1,
"description": "Unsupported media type",
"source": {
"code": "text",
"name": "text"
}
},
"tags": [
"text"
],
"shortLinks": {
"domain": "text"
},
"scheduledFor": "2025-03-28T19:11:21.734Z",
"body": {
"type": "text",
"text": {
"text": "text",
"attachments": [
{
"mediaUrl": "https://example.com",
"filename": "text",
"inline": true
}
],
"actions": [
{
"type": "link",
"link": {
"text": "text",
"url": "text"
}
}
],
"metadata": {
"subject": "text",
"headers": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"whatsapp": {
"previewUrl": true
},
"line": {
"emoji": {
"items": [
{
"index": 1,
"productId": "text",
"emojiId": "text"
}
]
}
},
"telegram": {
"parseMode": "Markdown"
}
}
}
}
}
Message was accepted for processing