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

Send a message to a channel

POST/workspaces/{workspaceId}/channels/{channelId}/messages

Authorization

useraccessKey

Path parameters

workspaceId*string (uuid)

The ID of the workspace

channelId*string (uuid)

The ID for a channel

Body

application/json

senderSender (object)

receiver*Receiver (object)

referenceReference (string)

templatenullable Template (object)

metaMeta (object)

replyToReplyTo (object)

bodyMessageBody

notificationChannelNotification

capFrequencyboolean

If set to true, the frequency capping settings of the platform will be used to either allow or reject the message to a contact. Can only be set to true if the message is sent to a contact and .meta.extraInformation.useCase is marketing.

enableLinkTrackingboolean

If set to true and message is a test/campaign message, web tracking parameters will be appended to the links in the message.

tagsTags (array of Name-3 (string))

Tags to associate with the message. Tags are converted to lower case and tags that do not exist are automatically created. You can view your created tags in the UI. You can specify up to 10 tags per message.

shortLinksnullable ShortLinks (object)

SMS link shortening options. When using templates, please refer to the template level shortLinks instead.

scheduledForScheduledFor (string (date-time))

Scheduled time to send message at. Must be formated as RFC3339 timestamp. When set, the message status will be scheduled until it's sent. Messages scheduled for a time in the past or within 10 minutes of the request may be sent immediately. Messages scheduled farther than 35 days will be rejected.

validityValidity (integer)

Validity determines for how many seconds a message is valid. If none is provided, the channel message type will be used to determine it. A promotional, conversational or transactional channel message is valid for 36 hours (129600 seconds). A message sent from a 2FA channel is valid for 10 minutes (600 seconds).

any of

ChannelMessageCreateWithTemplateChannelMessageCreateWithBody

Response

202400404409422

Message was accepted for processing

Body

application/json

id*Id-2 (string (uuid))

channelId*ChannelId (string (uuid))

sender*one of

ChannelConnectorChannelContact

receiver*one of

ChannelConnectorChannelContacts

metaMeta (object)

referenceReference (string)

partsParts (array of object)

status*Status-3 (enum)

acceptedprocessingscheduledsentsending_faileddelivereddelivery_faileddeleted

reasonstring

directionDirection (enum)

incomingoutgoing

originnullable Origin (object)

replyToReplyTo (object)

lastStatusAt*string (date-time)

createdAt*string (date-time)

updatedAt*string (date-time)

detailsstring

This field is used to store additional information related to the message status.

failurenullable Failure (object)

tagsTags (array of Name-3 (string))

Tags to associate with the message. Tags are converted to lower case and tags that do not exist are automatically created. You can view your created tags in the UI. You can specify up to 10 tags per message.

shortLinksnullable ShortLinks (object)

SMS link shortening options. When using templates, please refer to the template level shortLinks instead.

scheduledForScheduledFor (string (date-time))

Scheduled time to send message at. Must be formated as RFC3339 timestamp. When set, the message status will be scheduled until it's sent. Messages scheduled for a time in the past or within 10 minutes of the request may be sent immediately. Messages scheduled farther than 35 days will be rejected.

any of

objectobject

Request

JavaScriptCurlPython

const response = await fetch('/workspaces/{workspaceId}/channels/{channelId}/messages', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer jwt",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "receiver": {}
    }),
});
const data = await response.json();

Response

202400404409422

{
  "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"
      }
    }
  },
  "receiver": {
    "connector": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "identifierValue": "text",
      "annotations": {
        "name": "text"
      }
    }
  },
  "meta": {
    "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",
          "price": {
            "currencyCode": "text"
          }
        }
      ]
    },
    "referredProduct": {
      "externalCatalogId": "text",
      "externalProductId": "text"
    },
    "email": {
      "subject": "text",
      "from": {
        "username": "text",
        "displayName": "text"
      }
    },
    "navigatorId": "123e4567-e89b-12d3-a456-426614174000",
    "navigatorMessageId": "123e4567-e89b-12d3-a456-426614174000"
  },
  "reference": "text",
  "parts": [
    {
      "platformReference": "text"
    }
  ],
  "status": "accepted",
  "reason": "text",
  "direction": "incoming",
  "origin": {
    "type": "text",
    "id": "text"
  },
  "replyTo": {
    "id": "text",
    "type": "message"
  },
  "lastStatusAt": "2024-09-20T03:55:05.247Z",
  "createdAt": "2024-09-20T03:55:05.247Z",
  "updatedAt": "2024-09-20T03:55:05.247Z",
  "details": "text",
  "failure": {
    "description": "Unsupported media type",
    "source": {
      "code": "text",
      "name": "text"
    }
  },
  "tags": [
    "text"
  ],
  "shortLinks": {
    "domain": "text"
  },
  "scheduledFor": "2024-09-20T03:55:05.247Z",
  "body": {
    "type": "text",
    "text": {
      "text": "text",
      "attachments": [
        {
          "mediaUrl": "https://example.com",
          "filename": "text",
          "inline": false
        }
      ],
      "actions": [
        {
          "type": "link",
          "link": {
            "text": "text",
            "url": "https://example.com"
          }
        }
      ],
      "metadata": {
        "subject": "text",
        "whatsapp": {
          "previewUrl": false
        },
        "line": {
          "emoji": {
            "items": [
              {
                "productId": "text",
                "emojiId": "text"
              }
            ]
          }
        }
      }
    }
  }
}

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": "[phone]"
     }
   ]
 },
 "body": {...}
}

Template

{
 "receiver": {
   "contacts": [
     {
       "identifierKey": "phonenumber",
       "identifierValue": "[phone]"
     }
   ]
 },
 "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": "[phone]"
     }
   ]
 },
 "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": "[phone]"
     }
   ]
 },
 "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" } ] }