Cue Docs
APIs

Messages API

The messages API allows you to send out messages to users on different channels. WhatsApp, Webchat and SMS (beta) are currently supported.

WhatsApp

If someone messages your WhatsApp Business number first, this is known as a User Initiated Conversation. WhatsApp then allows you to reply to this person for up to 24 hours since their last inbound message to you. You can use the API below to send these messages.

If you want to message a recipient first, WhatsApp considers this to be a Business Initiated Conversation. For this, you will need to use the Template API to send a WhatsApp template first and from then on you can use this API to send any follow-up messages for up to 24 hours after your template was sent or since the user's last reply to you.

to accepts a phone number or a BSUID such as GB.13491208865530274191. Use whichever you received in from on the inbound webhook. See WhatsApp usernames and BSUIDs.

Request Examples

Below are examples of how you can send various WhatsApp message types to recipients. See the authentication page for how to obtain a bearer token.

POST https://api.cuedesk.com/v1/messages
Authorization: Bearer <token>
Content-Type: application/json
{
  "message": {
    "channelType": "whatsapp",
    "to": "447576209857",
    "from": "447418371579", // your WhatsApp business number
    "clientReference": "541d2b80-7569-4774-8798-f89c3378bbfa", // Client reference shown in webhooks
    "type": "text",
    "content": {
      "text": "This is an outbound text message"
    }
  }
}
{
  "message": {
    "channelType": "whatsapp",
    "to": "447576209857",
    "from": "447418371579",
    "clientReference": "541d2b80-7569-4774-8798-f89c3378bbfa",
    "type": "image",
    "content": {
      "url": "https://example.com/image.png",
      "caption": "This is an outbound image with a caption"
    }
  }
}
{
  "message": {
    "channelType": "whatsapp",
    "to": "447576209857",
    "from": "447418371579",
    "clientReference": "541d2b80-7569-4774-8798-f89c3378bbfa",
    "type": "video",
    "content": {
      "url": "https://example.com/video.mp4",
      "caption": "This is an outbound video with a caption"
    }
  }
}
{
  "message": {
    "channelType": "whatsapp",
    "to": "447576209857",
    "from": "447418371579",
    "clientReference": "541d2b80-7569-4774-8798-f89c3378bbfa",
    "type": "file",
    "content": {
      "url": "https://example.com/file.pdf",
      "caption": "This is an outbound file with a caption"
    }
  }
}
{
  "message": {
    "channelType": "whatsapp",
    "to": "447576209857",
    "from": "447418371579",
    "clientReference": "541d2b80-7569-4774-8798-f89c3378bbfa",
    "type": "audio",
    "content": {
      "url": "https://example.com/audio.mp3"
    }
  }
}
{
  "message": {
    "channelType": "whatsapp",
    "to": "447576209857",
    "from": "447418371579",
    "clientReference": "541d2b80-7569-4774-8798-f89c3378bbfa",
    "type": "location",
    "content": {
      "latitude": "51.500862746626005",
      "longitude": "-0.12458248627792581"
    }
  }
}
{
  "message": {
    "channelType": "whatsapp",
    "to": "447576209857",
    "from": "447418371579", // your WhatsApp business number
    "clientReference": "541d2b80-7569-4774-8798-f89c3378bbfa",
    "type": "button",
    "content": {
      "header": {
        "type": "text", // Can be "text", "image", "video", "file" or "audio".
        "value": "Welcome" // Text for text header or media URL for other header types.
      },
      "body": "Hey there, what can we help you with today?",
      "footer": "Choose an option", // Optional footer value
      "buttons": [
        {
          "id": "1", // Each button must have a unique ID
          "title": "Check order status"
        },
        {
          "id": "2",
          "title": "My account"
        },
        {
          "id": "3",
          "title": "Chat to agent"
        }
      ]
    }
  }
}
{
  "message": {
    "channelType": "whatsapp",
    "to": "447576209857",
    "from": "447418371579", // your WhatsApp business number
    "clientReference": "541d2b80-7569-4774-8798-f89c3378bbfa",
    "type": "list",
    "content": {
      "header": {
        "type": "text",
        "value": "Welcome"
      },
      "body": "Hey there, what can we help you with today?",
      "footer": "Choose an option", // Optional footer value
      "sections": [
        {
          "title": "My options", // Section title
          "items": [
            {
              "id": "1", // each option must have a unique ID
              "title": "Check order status",
              "description": "Search for your order number"
            },
            {
              "id": "2",
              "title": "My account",
              "description": "Manage your account settings"
            },
            {
              "id": "3",
              "title": "Chat to agent",
              "description": "Speak to a human"
            },
            {
              "id": "4",
              "title": "Give feedback",
              "description": "Let us know your thoughts"
            }
            // you can have up to 10 items per section
            // You can have up to 10 section objects
          ]
        }
      ]
    }
  }
}

Responses

A successful request will be responded to with a 202 Accepted status code. This is because the message still has to be sent upstream to WhatsApp where it can still fail. For example, if the message has been sent outside of the 24 hour reply window or the recipient's phone number is not on WhatsApp.

It is therefore strongly recommended that you look into setting up a message status update webhook to be notified about message failures.

Webchat

Request Examples

Below are examples of how you can send various Webchat message types to recipients. See the authentication page for how to obtain a bearer token.

POST https://api.cuedesk.com/v1/messages
Authorization: Bearer <token>
Content-Type: application/json
{
  "message": {
    "channelType": "webchat",
    "to": "GNVyvzreqPJe4uoAkP0fbHGAmx7FiuPbYMFj", // The contact's identifier
    "from": "83208a8b-9a71-4223-8252-a73a6f1f3b85", // Your webchat channel's identifier
    "sessionUuid": "ff14af09-620d-4bca-bcb5-1aaa95cb0e1c", // The session's UUID
    "clientReference": "541d2b80-7569-4774-8798-f89c3378bbfa", // Client reference shown in webhooks
    "type": "text",
    "content": {
      "text": "This is an outbound text message"
    }
  }
}
{
  "message": {
    "channelType": "webchat",
    "to": "GNVyvzreqPJe4uoAkP0fbHGAmx7FiuPbYMFj",
    "from": "83208a8b-9a71-4223-8252-a73a6f1f3b85",
    "sessionUuid": "ff14af09-620d-4bca-bcb5-1aaa95cb0e1c",
    "clientReference": "541d2b80-7569-4774-8798-f89c3378bbfa",
    "type": "image",
    "content": {
      "url": "https://example.com/image.png",
      "caption": "This is an outbound image with a caption"
    }
  }
}
{
  "message": {
    "channelType": "webchat",
    "to": "GNVyvzreqPJe4uoAkP0fbHGAmx7FiuPbYMFj",
    "from": "83208a8b-9a71-4223-8252-a73a6f1f3b85",
    "sessionUuid": "ff14af09-620d-4bca-bcb5-1aaa95cb0e1c",
    "clientReference": "541d2b80-7569-4774-8798-f89c3378bbfa",
    "type": "video",
    "content": {
      "url": "https://example.com/video.mp4",
      "caption": "This is an outbound video with a caption"
    }
  }
}
{
  "message": {
    "channelType": "webchat",
    "to": "GNVyvzreqPJe4uoAkP0fbHGAmx7FiuPbYMFj",
    "from": "83208a8b-9a71-4223-8252-a73a6f1f3b85",
    "sessionUuid": "ff14af09-620d-4bca-bcb5-1aaa95cb0e1c",
    "clientReference": "541d2b80-7569-4774-8798-f89c3378bbfa",
    "type": "file",
    "content": {
      "url": "https://example.com/file.pdf",
      "caption": "This is an outbound file with a caption"
    }
  }
}
{
  "message": {
    "channelType": "webchat",
    "to": "GNVyvzreqPJe4uoAkP0fbHGAmx7FiuPbYMFj",
    "from": "83208a8b-9a71-4223-8252-a73a6f1f3b85",
    "sessionUuid": "ff14af09-620d-4bca-bcb5-1aaa95cb0e1c",
    "clientReference": "541d2b80-7569-4774-8798-f89c3378bbfa",
    "type": "audio",
    "content": {
      "url": "https://example.com/audio.mp3",
      "caption": "This is an outbound audio with a caption"
    }
  }
}
{
  "message": {
    "channelType": "webchat",
    "to": "GNVyvzreqPJe4uoAkP0fbHGAmx7FiuPbYMFj",
    "from": "83208a8b-9a71-4223-8252-a73a6f1f3b85",
    "sessionUuid": "ff14af09-620d-4bca-bcb5-1aaa95cb0e1c",
    "clientReference": "541d2b80-7569-4774-8798-f89c3378bbfa",
    "type": "button",
    "content": {
      "header": {
        "type": "image", // Can be "image", "video" or "file".
        "value": "https://example.com/image.png" // Media URL.
      },
      "body": "Hey there, what can we help you with today?",
      "buttons": [
        {
          "id": "1", // Each button must have a unique ID
          "title": "Check order status"
        },
        {
          "id": "2",
          "title": "My account"
        },
        {
          "id": "3",
          "title": "Chat to agent"
        }
      ]
    }
  }
}

Responses

A successful request will be responded to with a 202 Accepted status code.

SMS

Beta

The SMS Messages API is currently in beta. If you would like to join the beta, please contact us.

Request Examples

Below is an example of how you can send an SMS text message to a recipient. See the authentication page for how to obtain a bearer token.

POST https://api.cuedesk.com/v1/messages
Authorization: Bearer <token>
Content-Type: application/json
Idempotency-Key: <unique-key>
{
  "message": {
    "channelType": "sms",
    "from": "44600145034", // your SMS channel number
    "to": "44787675745", // recipient number
    "clientReference": "sms-f89c3378bbfa", // Reference appears in update webhooks
    "type": "text",
    "content": {
      "text": "Hi there 👋 your car is ready for collection. We washed it too ✨"
    }
  }
}

Responses

A successful request will be responded to with a 202 Accepted status code.

{
  "messageUuid": "ee02281a-e495-4941-9613-1098c485d25e",
  "encoding": "ucs2",
  "segments": 1 // number of message parts
}

Set up a message status update webhook to be notified about message delivery updates. An SMS message can have the status submitted, delivered, rejected or undeliverable. SMS has no read status.

Idempotency

Send an Idempotency-Key header to safely retry a request after a timeout or a network error. A retry with the same key does not send the SMS a second time. The header is optional and is only supported for SMS.

  • Use a unique value for each message, such as a UUID. The maximum length is 255 characters.
  • Keys are scoped to your workspace and are kept for 48 hours.
Retry with the same keyResponse
Same request body, original request accepted202 Accepted with the original messageUuid. The SMS is not sent again.
Same request body, original request in progress409 Conflict with code idempotency_key_in_flight. Retry after a short wait.
Different request body422 Unprocessable Entity with code idempotency_key_reused.

Duplicate content

Identical messages (the same from, to, type and content) sent within 60 seconds of an accepted message are rejected with 409 Conflict and Duplicate message content detected., with or without an Idempotency-Key. If you retry an accepted request within 60 seconds, you get this response, not the replayed 202.

Authentication

Authenticate API requests with a Bearer token from the API Tokens settings of your Cue workspace.

V1

Create, validate, cancel and track bulk WhatsApp template broadcasts with the Broadcast API V1.

On this page

WhatsAppRequest ExamplesResponsesWebchatRequest ExamplesResponsesSMSRequest ExamplesResponsesIdempotency