Sending SMS messages
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
Send a message to a channel
Authorizations
Path parameters
workspaceIdstring · uuidRequired
The ID of the workspace
channelIdstring · uuidRequired
The ID for a channel
Body
all ofOptional
and
any ofOptional
object · ChannelMessageCreateWithTemplateOptional
object · ChannelMessageCreateWithBodyOptional
Responses
202
Message was accepted for processing
application/json
Responseall of
and
any ofOptional
or
400
The request did not pass validation
application/json
404
The request did not pass validation
application/json
409
Creating the message was not possible because of conflicting conditions
application/json
422
The request did not pass validation
application/json
post
POST /workspaces/{workspaceId}/channels/{channelId}/messages HTTP/1.1
Host:
Authorization: Bearer jwt
Content-Type: application/json
Accept: */*
Content-Length: 2682
{
"sender": {
"connector": {
"identifierValue": "[email protected]",
"annotations": {
"name": "text"
}
}
},
"receiver": {
"contacts": [
{
"id": "a1405560-c8d3-4b1a-877d-3f449ad95352",
"identifierKey": "emailaddress",
"identifierValue": "[email protected]",
"type": "cc",
"identifiers": [
{
"identifierKey": "emailaddress",
"identifierValue": "[email protected]"
}
],
"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"
}
],
"settings": {
"useMmLite": true
}
},
"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,
"contentId": "text"
}
],
"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-07-30T10:05:32.520Z",
"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-07-30T10:05:32.520Z",
"createdAt": "2025-07-30T10:05:32.520Z",
"updatedAt": "2025-07-30T10:05:32.520Z",
"details": "text",
"failure": {
"code": 1,
"description": "Unsupported media type",
"source": {
"code": "text",
"name": "text"
}
},
"tags": [
"text"
],
"shortLinks": {
"domain": "text"
},
"scheduledFor": "2025-07-30T10:05:32.520Z",
"body": {
"type": "text",
"text": {
"text": "text",
"attachments": [
{
"mediaUrl": "https://example.com",
"filename": "text",
"inline": true,
"contentId": "text"
}
],
"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",
"length": 1
}
]
}
},
"telegram": {
"parseMode": "Markdown"
}
}
}
}
}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": {...}
}SMS messages
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": {...}
}Send an SMS message
To send an SMS text message set the message body as follows:
{
"type": "text",
"text": {
"text": "Single text message"
}
}MMS messages
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.
Image
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"
}
]
}
}
Single image message with text
{
"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"
}
}
Single image message with text and title
{
"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"
}
}
}
Multiple image message
When sending multiple image messages it is possible to send up to an array of 10 media URLs.
{
"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"
}
]
}
}
Multiple image message with text
{
"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"
}
}
Multiple image message with text and title
{
"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"
}
}
}
File
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"
}
]
}
}
Single file message with text
{
"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"
}
}
Single file message with text and title
{
"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"
}
}
}
Multiple 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"
},
{
"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"
}
}
Multiple file message with text
{
"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"
}
}
Multiple file message with text and title
{
"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"
}
}
}
Template messages
Using studio 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.
The examples below must be set in the message template field
{
"receiver": {
"contacts": [
{
"identifierValue": "+31612345678"
}
]
},
"template": {...}
}Text templates
Text templates will be sent as SMS messages and are compatible with all SMS channels
{ "projectId":"ce6a2fd6-b2fa-4f5a-a2cd-f3bd15883318",
"version":"latest",
"locale":"en",
"parameters":[
{
"type":"string",
"key":"name",
"value":"Robert"
}
]
}
Last updated
Was this helpful?