Search... Close

Message types

This section gives you an overview of how you can structure your Messages API request for different message types and channels and see some example output.

Message types contain a number of sections including a header, body, footer, and buttons depending on the message type you are using for your communication. This structure intuitively follows how the message is rendered on the user's phone. For example, you may want to include some header text when sending an image or as part of a WhatsApp template. This is all possible with Messages API.

Read on to learn more about configuring the following message types with Messages API.

Not all messaging channels support all message types. For a deeper dive into message types per channel then see the channel pages documentation:

Text

Send a simple text message using Messages API.

Text message types are natively supported by:

SMS
MMS
WhatsApp
RCS
Viber Business Messages

Example

{
  "messages" : [ {
    "channel" : "SMS"
    "content" : {
      "body" : {
        "text" : "Follow the link athleete.com/event-details for more details. See you next week!"
        "type" : "TEXT"
      }
    },
    "sender": "441234567890",
    "destinations" : [ {
      "to" : "440987654321"
    } ],
   } ]
}

Output

Buttons

Add buttons to your communication to facilitate interaction.

Buttons are natively supported by:

WhatsApp
RCS
Viber Business Messages

INFO

Viber Business Messages only supports single buttons in messages. This can be achieved by using a single button block in your request rather than multiple button blocks.

INFO

If you are using a channel that does not support buttons as a message type then you can use the omitUnsupportedElements parameter as part of your API request to remove the unsupported element and deliver the message anyway without throwing an error.

Example button

{
  "messages" : [ {
    "channel" : "WHATSAPP"
    "content" : {
      "body" : {
        "text" : "Thank you for joining us on Athleete Unlocked! Would you like to subscribe for future Athleete events?",
        "type" : "TEXT"
      },
      "buttons" : [ {
        "type" : "REPLY"
        "text" : "Yes",
        "postbackData" : "true",
       }, {  
        "type" : "REPLY"         
        "text" : "No",
        "postbackData" : "false",
       } ]
    },
    "options" : {
        "omitUnsupportedElements" : true
    },
    "sender": "441234567890",
    "destinations" : [ {
      "to" : "440987654321"
    } ],
  } ]
}

Output

Image

Send an image in your message.

Images are natively supported by

MMS
WhatsApp
RCS
Viber Business Messages

INFO

Sending an SMS with an image will render the image URL.

Example image

{
  "messages" : [ {
    "channel" : "WHATSAPP"
    "content" : {
      "body" : {
        "type" : "IMAGE"
        "url" : "http://homestore/image.png",
        "text" : "Spring is around the corner! Check out what we have in store for you.",  
      },
    },
    "options" : {
        "omitUnsupportedElements" : true
    },    
    "sender" : "441234567890"
    "destinations" : [ {
      "to" : "440987654321"
    } ]
  } ],
}

Output

Image with header

Add data such as caption text inside the message header.

Images with headers are natively supported by:

Example image with header

{
  "messages" : [ {
    "channel" : "WHATSAPP"
    "content" : {
     "header" : {
        "text" : "Spring is around the corner!"
      },
      "body" : {
        "type" : "IMAGE"
        "url" : "http://homestore/image.png",
        "text" : "Check out what we have in store for you.",  
      },
    },
    "options" : {
        "omitUnsupportedElements" : true
    },    
    "sender" : "441234567890"
    "destinations" : [ {
      "to" : "440987654321"
    } ]
  } ],
}

Output

Templates

Send messages from predefined templates.

Template message types are natively supported by:

Message templates contain various sections including header, body, footer, and buttons. When sending template messages using the Messages API it is optional if you want to include header and button elements in your communication.

Templates with headers represent sending media in a templated message. See Templates with Headers below for some example requests.

Example template

{
  "messages": [
    {
       "channel": "WHATSAPP",
       "content": {
        "body": {
          "1": "Jane",
          "2": "Doe",
          "type": "TEXT"
        },
      },
      "sender": "441234567890",
      "destinations": [
        {
          "to": "440987654321"
        }
      ],
      "template": {
        "templateName": "account_update",
        "language": "en_GB"
      }
    }
  ]
}

Output

Templates with headers

Use Messages API to send template messages that contain data inside the header:

Document
Image
Video
Location
Text

The below example shows a WhatsApp template with a document header using the Messages API.

You can also adapt the header content to include image, location, and video as needed for your communication scenario.

Example template with header

 {
  "messages": [
    {
       "channel": "WHATSAPP",
       "content": {
        "header": {
          "url": "https://mydocument.com",
          "filename": "Filename.doc",
          "type": "DOCUMENT"
        },
        "body": {
          "1": "Jane",
          "2": "Doe",
          "type": "TEXT"
        },
      },
      "sender": "441234567890",
      "destinations": [
        {
          "to": "440987654321"
        }
      ],
      "template": {
        "templateName": "receipt",
        "language": "en_GB"
      }
    }
  ]
}

Output

Templates with buttons

Templates can also include buttons. The below example shows how you can render templates with buttons using with Messages API.

You can render URL buttons and Reply buttons.

Example template with buttons

{
  "messages": [
    {
       "channel": "WHATSAPP",
       "content": {
        "body": {
          "1": "Jane",
          "2": "Doe",
          "type": "TEXT"
        },
        "buttons": [
          {
            "suffix": "search?q=123456",
            "type": "OPEN_URL"
          }
        ]
      },
      "sender": "441234567890",
      "destinations": [
        {
          "to": "440987654321"
        }
      ],
      "template": {
        "templateName": "appointment_update",
        "language": "en_GB"
      }
    }
  ]
}

Output

Document

Send files through your chosen messaging channel.

Document message type are natively supported by:

MMS
WhatsApp
Viber Business Messages

NOTE

Channel availability and output depends on the message elements you include in your request. For example, Viber Business Messages does not support documents with filename.

NOTE

If you are using a channel that does not natively support document as a message type then you can use the omitUnsupportedElements parameter as part of your API request to remove the unsupported element and deliver the message anyway without throwing an error.

Example document

{
  "messages" : [ {
    "channel" : "WHATSAPP"
    "content" : {
      "body" : {
        "type" : "DOCUMENT"
        "url" : "http://my.domain/document.pdf",  
      },
    },
    "options" : {
        "omitUnsupportedElements" : true
    },    
    "sender" : "441234567890"
    "destinations" : [ {
      "to" : "440987654321"
    } ]
  } ],

Output

Video

Send video as part of your communication.

Video message type are natively supported by:

MMS
WhatsApp
RCS
Viber Business Messages

NOTE

If you are using a channel that does not natively support videos as a message type then you can use the omitUnsupportedElements parameter as part of your API request to remove the unsupported element and deliver the message anyway without throwing an error.

Example video

{
  "messages" : [ {
    "channel" : "WHATSAPP"
    "content" : {
      "body" : {
        "type" : "VIDEO"
        "url" : "http://my.domain/video.mp4", 
      },
    },
    "options" : {
        "omitUnsupportedElements" : true
    },    
    "sender" : "441234567890"
    "destinations" : [ {
      "to" : "440987654321"
    } ]
  } ],
}

Output

Getting started Send a message