Messages API

The messages API allows you to send out messages to users on different channels. WhatsApp is currently the only channel that is supported. We're planning to introduce the ability to send messages for web chat, Facebook Messenger and many other channel types in future.

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.

info

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.

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

Text

{
  "message": {
    "channelType": "whatsapp",
    "to": "447576209857",
    "from": "447418371579", // your WhatsApp business number
    "type": "text",
    "content": {
      "text": "This is an outbound text message"
    }
  }
}

Image

{
  "message": {
    "channelType": "whatsapp",
    "to": "447576209857",
    "from": "447418371579",
    "type": "image",
    "content": {
      "url": "https://example.com/image.png",
      "caption": "This is an outbound image with a caption"
    }
  }
}

Video

{
  "message": {
    "channelType": "whatsapp",
    "to": "447576209857",
    "from": "447418371579",
    "type": "video",
    "content": {
      "url": "https://example.com/video.mp4",
      "caption": "This is an outbound video with a caption"
    }
  }
}

File

{
  "message": {
    "channelType": "whatsapp",
    "to": "447576209857",
    "from": "447418371579",
    "type": "file",
    "content": {
      "url": "https://example.com/file.pdf",
      "caption": "This is an outbound file with a caption"
    }
  }
}

Audio

{
  "message": {
    "channelType": "whatsapp",
    "to": "447576209857",
    "from": "447418371579",
    "type": "audio",
    "content": {
      "url": "https://example.com/audio.mp3"
    }
  }
}

Location

{
  "message": {
    "channelType": "whatsapp",
    "to": "447576209857",
    "from": "447418371579",
    "type": "location",
    "content": {
      "latitude": "51.500862746626005",
      "longitude": "-0.12458248627792581"
    }
  }
}

Buttons

{
  "message": {
    "channelType": "whatsapp",
    "to": "447576209857",
    "from": "447418371579", // your WhatsApp business number
    "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"
        }
      ]
    }
  }
}

List

{
  "message": {
    "channelType": "whatsapp",
    "to": "447576209857",
    "from": "447418371579", // your WhatsApp business number
    "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

Text

{
  "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
    "type": "text",
    "content": {
      "text": "This is an outbound text message"
    }
  }
}

Image

{
  "message": {
    "channelType": "webchat",
    "to": "GNVyvzreqPJe4uoAkP0fbHGAmx7FiuPbYMFj",
    "from": "83208a8b-9a71-4223-8252-a73a6f1f3b85",
    "sessionUuid": "ff14af09-620d-4bca-bcb5-1aaa95cb0e1c",
    "type": "image",
    "content": {
      "url": "https://example.com/image.png",
      "caption": "This is an outbound image with a caption"
    }
  }
}

Video

{
  "message": {
    "channelType": "webchat",
    "to": "GNVyvzreqPJe4uoAkP0fbHGAmx7FiuPbYMFj",
    "from": "83208a8b-9a71-4223-8252-a73a6f1f3b85",
    "sessionUuid": "ff14af09-620d-4bca-bcb5-1aaa95cb0e1c",
    "type": "video",
    "content": {
      "url": "https://example.com/video.mp4",
      "caption": "This is an outbound video with a caption"
    }
  }
}

File

{
  "message": {
    "channelType": "webchat",
    "to": "GNVyvzreqPJe4uoAkP0fbHGAmx7FiuPbYMFj",
    "from": "83208a8b-9a71-4223-8252-a73a6f1f3b85",
    "sessionUuid": "ff14af09-620d-4bca-bcb5-1aaa95cb0e1c",
    "type": "file",
    "content": {
      "url": "https://example.com/file.pdf",
      "caption": "This is an outbound file with a caption"
    }
  }
}

Audio

{
  "message": {
    "channelType": "webchat",
    "to": "GNVyvzreqPJe4uoAkP0fbHGAmx7FiuPbYMFj",
    "from": "83208a8b-9a71-4223-8252-a73a6f1f3b85",
    "sessionUuid": "ff14af09-620d-4bca-bcb5-1aaa95cb0e1c",
    "type": "audio",
    "content": {
      "url": "https://example.com/audio.mp3",
      "caption": "This is an outbound audio with a caption"
    }
  }
}

Buttons

{
  "message": {
    "channelType": "webchat",
    "to": "GNVyvzreqPJe4uoAkP0fbHGAmx7FiuPbYMFj",
    "from": "83208a8b-9a71-4223-8252-a73a6f1f3b85",
    "sessionUuid": "ff14af09-620d-4bca-bcb5-1aaa95cb0e1c",
    "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.