Skip to content
Last updated

In addition to the text messages highlighted in our getting started guides, Conversation API supports sending various generic message types and template message types.

Generic message types allow you to send the same type of message on multiple Conversation API channels. If the generic message type isn't inherently supported by the channel it's set to be sent on, Conversation API will transcode the message for sending.

Conversation API also supports sending template messages where all or parts of the message content is pre-defined. The message template can also contain dynamic content which is populated when sending the message using template parameters.

Note:

In order to populate and send a template message, the corresponding template must exist and you must know its identifying information. For more information on creating, managing, and identifying templates, see our template management documentation.

Generic message types and most template message types can be sent on any channel supported by Conversation API.

Sending generic message types

Conversation API uses generic message types in order to send the same message to multiple channels. The following table gives a quick overview of which channels have native support for each generic message type. In cases in which the channel doesn't natively support the message type, the message will be transcoded. You may use any of these calls on any of the channels supported by Conversation API.

ChannelGeneric Message Type
Text Media Choice Card Carousel Location List
WhatsApp
SMS
Facebook Messenger
Instagram
MMS
RCS
Viber Business Message
Telegram
KakaoTalk
LINE
WeChat
Sinch Chat
Sinch Push

The following pages provide payload samples that allow you to send each of the generic message types displayed in the table above. Additionally, each section links to a page that provides examples of how the message will display when sent on the various channels supported by Conversation API:

Sending text messages

The payload for sending a text message using Conversation API is displayed below:

{
  "app_id": "{APP_ID}",
  "recipient": {
    "identified_by": {
      "channel_identities": [
        {
          "channel": "{CHANNEL}",
          "identity": "{IDENTITY}"
        }
      ]
    }
  },
  "message": {
    "text_message": {
      "text": "This is a text message."
    }
  }
}

For examples of how these messages may render on the different channels supported by Conversation API and channel-specific requirements, see the text message page.

Sending media messages

The payload for sending a media message using Conversation API is displayed below:

{
  "app_id": "{APP_ID}",
  "recipient": {
    "identified_by": {
      "channel_identities": [
        {
          "channel": "{CHANNEL}",
          "identity": "{IDENTITY}"
        }
      ]
    }
  },
  "message": {
    "media_message": {
      "url": "{URL_TO_MEDIA}"
    }
  }
}

For examples of how these messages may render on the different channels supported by Conversation API and channel-specific requirements, see the media message page.

Sending choice messages

The payload for sending a choice message using Conversation API is displayed below:

{
  "app_id": "{APP_ID}",
  "recipient": {
    "identified_by": {
      "channel_identities": [
        {
          "channel": "{CHANNEL}",
          "identity": "{IDENTITY}"
        }
      ]
    }
  },
  "message": {
    "choice_message": {
      "text_message": {
        "text": "Friendly reminder of your appointment tomorrow at 10AM. Please confirm your booking by replying below."
      },
      "choices": [
        {
          "text_message": {
            "text": "Confirm"
          }
        },
        {
          "text_message": {
            "text": "Cancel"
          }
        }
      ],
      "message_properties": [
        {
          "whatsapp_footer": "WhatsApp footer text"
        }
      ]
    }
  }
}

For examples of how these messages may render on the different channels supported by Conversation API and channel-specific requirements, see the choice message page.

Sending card messages

The payload for sending a card message using Conversation API is displayed below:

{
  "app_id": "{APP_ID}",
  "recipient": {
    "identified_by": {
      "channel_identities": [
        {
          "channel": "{CHANNEL}",
          "identity": "{IDENTITY}"
        }
      ]
    }
  },
  "message": {
    "card_message": {
      "title": "Sign up for our newsletter",
      "description": "Our weekly newsletter with deals and extra content!",
      "media_message": {
        "url": "https://1vxc0v12qhrm1e72gq1mmxkf-wpengine.netdna-ssl.com/wp-content/uploads/2019/05/Sinch-logo-Events.png"
      },
      "choices": [
        {
          "text_message": {
            "text": "Sign up here"
          }
        }
      ],
      "message_properties": [
        {
          "whatsapp_header": "WhatsApp header text"
        }
      ]
    }
  }
}

For examples of how these messages may render on the different channels supported by Conversation API and channel-specific requirements, see the card message page.

The payload for sending a carousel message using Conversation API is displayed below:

{
  "app_id": "{APP_ID}",
  "recipient": {
    "identified_by": {
      "channel_identities": [
        {
          "channel": "{CHANNEL}",
          "identity": "{IDENTITY}"
        }
      ]
    }
  },
  "message": {
    "carousel_message": {
      "cards": [
        {
          "title": "Sign up for our weekly newsletter",
          "description": "Our weekly newsletter is filled with deals and extra content!",
          "media_message": {
            "url": "https://1vxc0v12qhrm1e72gq1mmxkf-wpengine.netdna-ssl.com/wp-content/uploads/2019/05/Sinch-logo-Events.png"
          },
          "choices": [
            {
              "text_message": {
                "text": "Sign up here"
              }
            }
          ]
        },
        {
          "title": "Visit our website",
          "description": "You can view your account and place orders from our convenient dashboard.",
          "media_message": {
            "url": "https://1vxc0v12qhrm1e72gq1mmxkf-wpengine.netdna-ssl.com/wp-content/uploads/2019/05/Sinch-logo-Events.png"
          },
          "choices": [
            {
              "url_message": {
                "title": "Website",
                "url": "https://www.sinch.com"
              }
            }
          ]
        },
        {
          "title": "Call our customer support line",
          "description": "Our dedicated support staff can answer your questions and concerns.",
          "media_message": {
            "url": "https://1vxc0v12qhrm1e72gq1mmxkf-wpengine.netdna-ssl.com/wp-content/uploads/2019/05/Sinch-logo-Events.png"
          },
          "choices": [
            {
              "call_message": {
                "title": "Support line",
                "phone_number": "46732000000"
              }
            }
          ]
        }
      ]
    }
  }
}

For examples of how these messages may render on the different channels supported by Conversation API and channel-specific requirements, see the carousel message page.

Sending location messages

The payload for sending a location message using Conversation API is displayed below:

{
  "app_id": "{APP_ID}",
  "recipient": {
    "identified_by": {
      "channel_identities": [
        {
          "channel": "{CHANNEL}",
          "identity": "{IDENTITY}"
        }
      ]
    }
  },
  "message": {
    "location_message": {
      "title": "Your ride is here!",
      "label": "Meet your driver at the specified address.",
      "coordinates": {
        "latitude": 55.610479,
        "longitude": 13.002873
      }
    }
  }
}

For examples of how these messages may render on the different channels supported by Conversation API and channel-specific requirements, see the location message page.

Sending list messages

Note:

Currently, list messages are only supported by the WhatsApp channel. List messages are not natively supported on channels other than WhatsApp, and they may not be transcoded into text on other channels.

The payload for sending a list message using Conversation API is displayed below:

{
  "app_id": "{APP_ID}",
  "recipient": {
    "identified_by": {
      "channel_identities": [
        {
          "channel": "{CHANNEL}",
          "identity": "{IDENTITY}"
        }
      ]
    }
  },
  "message": {
    "list_message": {
      "title": "Choose your icecream flavor",
      "description": "The best icecream in town!",
      "sections": [
        {
          "title": "Fruit flavors",
          "items": [
            {
              "choice": {
                "title": "Strawberry",
                "postback_data": "Strawberry postback"
              }
            },
            {
              "choice": {
                "title": "Blueberry",
                "postback_data": "Blueberry postback"
              }
            }
          ]
        },
        {
          "title": "Other flavors",
          "items": [
            {
              "choice": {
                "title": "Chocolate",
                "postback_data": "Chocolate postback"
              }
            },
            {
              "choice": {
                "title": "Vanilla",
                "postback_data": "Vanilla postback"
              }
            }
          ]
        }
      ],
      "message_properties": {
        "menu": "Menu text",
        "whatsapp_header": "WhatsApp header text"
      }
    }
  }
}

The payload for sending a product list message using Conversation API is displayed below:

{
  "app_id": "{APP_ID}",
  "recipient": {
    "identified_by": {
      "channel_identities": [
        {
          "channel": "{CHANNEL}",
          "identity": "{IDENTITY}"
        }
      ]
    }
  },
  "message": {
    "list_message": {
      "title": "Title for the list message with products",
      "description": "Description (or subtitle) for list message with products",
      "sections": [
        {
          "title": "Facebook product catalog item set name",
          "items": [
            {
              "product": {
                "id": "product_1_id",
                "marketplace": "FACEBOOK"
              }
            },
            {
              "product": {
                "id": "product_2_id",
                "marketplace": "FACEBOOK"
              }
            }
          ]
        }
      ],
      "message_properties": {
        "catalog_id": "id_of_catalog"
      }
    }
  }
}

For examples of how these messages may render on the different channels supported by Conversation API and channel-specific requirements, see the list message page.

Sending template messages

Conversation API supports sending template messages where all or parts of the message content is pre-defined. The message template can also contain dynamic content which is populated when sending the message using template parameters.

Note:

In order to populate and send a template message, the corresponding template must exist and you must know its identifying information. For more information on creating, managing, and identifying templates, see our template management documentation.

There are two types of templates which can be used when sending a template message:

  • Omni-channel
  • Channel-specific

The format of the omni-channel templates is exactly the same as the format of the message field of the messages:send request body. The omni-channel templates are stored and managed by Template Management API.

The channel-specific templates are stored and managed by the channels, and are only referenced when sending through Conversation API. Currently, WhatsApp, KakaoTalk, and WeChat templates are the only supported channel-specific templates, and they're stored by Facebook WhatsApp Business API, KakaoTalk, or WeChat.

Sending omni-channel templates

The omni-channel templates use Conversation API generic message format and therefore, can define a generic rich message or a concrete channel message by using the channel override feature of Conversation API.

It's easy to see how an omni-channel template will render on a specific channel by using the transcoding (messages:transcode) endpoint of the Conversation API.

The omni-channel templates are versioned and support storing message content for different languages.

Once an omni-channel template has been created, you can use it when sending messages using the Conversation API. For example:

{
  "app_id": "{APP_ID}",
  "recipient": {
    "identified_by": {
      "channel_identities": [
        {
          "channel": "{CHANNEL}",
          "identity": "{IDENTITY}"
        }
      ]
    }
  },
  "message": {
    "template_message": {
      "omni_template": {
        "template_id": "{OMNI_TEMPLATE_ID}",
        "version": "latest",
        "language_code": "en_US",
        "parameters": {}
      }
    }
  }
}

Sending channel-specific templates

With the Conversation API, you can also reference channel-defined templates when sending a template message.

Currently, WhatsApp, KakaoTalk, and WeChat are the only channels that have channel-specific templates.

  • WhatsApp templates can be created using either the Sinch Build Dashboard or the Provisioning API. They are then uploaded to and approved by Facebook, and are required to send messages outside of the customer care session.

    Note:

    In addition creating WhatsApp templates, you can also edit active WhatsApp templates using the Sinch Build Dashboard or the Provisioning API's Update a template in project call. However, you can only update an active template a maximum of once a day and ten times a month.

  • KakaoTalk templates (Alimtalk) are registered by Sinch on behalf of the customer and need to be approved by KakaoTalk. These templates are required to send messages, such as notifications or delivery status messages.

  • WeChat templates are pre-defined by WeChat. You must go to the Template Library section in your WeChat Admin portal, choose the templates that fit your use cases, and add those templates to your account.

Once a template has been created and approved, you can start using it with Conversation API to send template messages to the channel. For example:

{
  "app_id": "{APP_ID}",
  "recipient": {
    "identified_by": {
      "channel_identities": [
        {
          "channel": "WHATSAPP",
          "identity": "{WHATSAPP_IDENTITY}"
        }
      ]
    }
  },
  "message": {
      "template_message": {
          "channel_template": {
              "WHATSAPP": {
                  "template_id": "{WHATSAPP_TEMPLATE_NAME}",
                  "language_code": "en",
                  "parameters": {
                      "header[1]image.link": "https://example.com",
                      "body[1]text": "Value of first parameter"
                  }
              }
          }
      }
  },
  "channel_priority_order": [
      "WHATSAPP"
  ]
}

The snippet above sends a template message to a recipient with {WHATSAPP_IDENTITY} channel identity and tries only the WHATSAPP channel. The message being sent is a template message referencing a WhatsApp channel-defined template with ID {WHATSAPP_TEMPLATE_NAME} and language code en.

It also specifies the parameters defined in the template as part of parameters field.

Note the following:

  • When sending a WhatsApp template message on the WhatsApp channel, the template_id field must be populated with the name of the WhatsApp template (inseated of any Meta template ID assigned to the WhatsApp template).

  • When sending a WhatsApp template message, you must specify the language_code property, regardless of whether the default_translation property is set.

  • When sending an AlimTalk template message on the KakaoTalk channel, the language_code value is not used. When you register a KakaoTalk AlimTalk message template, each language has its own unique template ID. Therefore, it is not possible to register multiple language codes to the same template_id for KakaoTalk templates.

You can read more about sending channel-specific templates on the following pages:

Omni- and channel-specific templates can both be used when sending a message. This is useful in several scenarios. For example, you can enable channel fallback in case the recipient has no capability on the WhatsApp channel:

{
  "app_id": "{APP_ID}",
  "recipient": {
    "identified_by": {
      "channel_identities": [
        {
          "channel": "WHATSAPP",
          "identity": "{WHATSAPP_IDENTITY}"
        },
        {
          "channel": "SMS",
          "identity": "{SMS_IDENTITY}"
        }
      ]
    }
  },
  "message": {
      "template_message": {
          "channel_template": {
              "WHATSAPP": {
                  "template_id": "{WHATSAPP_TEMPLATE_NAME}",
                  "language_code": "en",
                  "parameters": {
                      "header[1]image.link": "https://example.com",
                      "body[1]text": "Value of first parameter"
                  }
              }
          },
          "omni_template": {
              "template_id": "<Omni Template Id>",
              "version": "<Omni Version Id>",
              "language_code": "en",
              "parameters": {
                  "name": "Ms Smith"
              }
          }
      }
  },
  "channel_priority_order": [
      "WHATSAPP", "SMS"
  ],
  "channel_properties": {
    "SMS_SENDER": "{SMS_SENDER}"
  }
}

The Conversation API will use the channel-specific template if one exists for the channel. Otherwise, it will fallback to the omni template.