On this page

Outbound Messaging

When messaging a contact, the message needs to have "agent" as the role value to reach the consumer: all messages in a contact conversation's main stream with role "agent" are outbound messages.

Plain text messages

Talk to the contact.

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

{
    "type": "chat",
    "role": "agent",
    "text": "Here is some information"
}

context

Provide a touchpoint parameter to target a not currently selected touchpoint.

A list of items with actions is shown as a carousel in rich consumer media.

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

{
  "type": "card",
  "text": "Favorite food?",
  "role": "agent",
  "items": [
    {
        "title": "Tacooos",
        "actions": [
            {
              "type": "link",
              "text": "Taco 1",
              "url": "http://example.org/taco.html",
              "uri": "http://example.org/taco.html"
            }
        ]
      },
      {
        "title": "Burritoos",
        "actions": [
            {
              "type": "link",
              "text": "Burro 1",
              "url": "http://example.org/burrito.html",
              "uri": "http://example.org/burrito.html"
            }
        ]
      }
  ]
}

context

See the List Items section in chapter 3 for a more extensive example.

Postback buttons

Postback buttons (actions of type 'postback') can be clicked multiple times by the recipient.

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

{
  "text": "Favorite color?",
  "role": "agent",
  "actions": [
    {
      "text": "Red",
      "payload": "red",
      "type": "postback"
    },
    {
      "text": "Blue",
      "payload": "blue",
      "type": "postback"
    }
  ]
}

context

Please review the Action Buttons section of chapter 3 for more information on postbacks.

Suggested QuickReplies

Actions with type "reply" are shown as buttons in the bottom of the consumer UI.

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

{
    "text":"Which do you prefer?",
    "role": "agent",
    "actions": [
      {
        "type": "reply",
        "text": "Tacos",
        "iconUrl": "http://example.org/taco.png",
        "payload": "TACOS"
      },
      {
        "type": "reply",
        "text": "Burritos",
        "iconUrl": "http://example.org/burrito.png",
        "payload": "BURRITOS"
      }
    ]
}

context

Please review the Action Buttons section of chapter 3 for more information on quick replies.

Sending files and images

Files and images are just regular chat or card messages, but with a specific content type and the url specified in message.text.

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

{
    "role": "agent",
    "text": "http://infolab.stanford.edu/pub/papers/google.pdf",
    "contentType": "application/pdf",
    "meta": {
        "title": "Google"
    }
}

context

Typing indicators

Delaying a message (by message.delay miliseconds) shows a typing indicator on the consumer end. It's shown for about two seconds before the end of the delay for longer texts (more than 40 characters) and long delays (more than two seconds). For smaller delays or shorter message text, the typing indicator is shown for just one second.

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

{
    "type": "chat",
    "role": "agent",
    "text": "I was typing before you saw this.",
    "delay": 1000
}

context

One-way SMS notifications from an alphanumeric Sender ID

Twilio Alphanumeric Sender ID allows you to set your company name or brand as the Sender ID when sending one-way SMS messages to supported countries. Alphanumeric Sender IDs may be up to 11 characters. Accepted characters include both upper- and lower-case ASCII letters, the digits 0 through 9, and space: A-Z, a-z, 0-9. They may not be only numbers. Review the documentation at Twilio for more information.

Specifying the meta.SenderID property will send the message as a one-way SMS:

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

{
    "text": "Hello",
    "touchpoint": "sms",
    "role": "agent",
    "meta": {
        "SenderID": "Tims Truckshop"
    }
}

WhatsApp Message Templates

In the WhatsApp channel, sending free-form text is prohibited after 24 hours of consumer inactivity (the last message by the contact); after that time, only Message Templates are allowed. Message Templates are message formats for common reusable messages a business may want to send. Businesses must use Message Templates for sending notifications to customers.

To create a WhatsApp Message Template, add the following variables (of the Facebook-approved registered template) as meta vars:

  • elementName (eg "car_ready")
  • namespace (eg "56cca817_5273_b9be_fc60_13623ff82b1e")
  • language (optional, two- or four-letter language code like "nl_NL")

Request: POST /v2/conversations/590bd49f458b716046347f47/messages

{
    "role": "agent",
    "text": "Your car is ready to be picked up!",
    "touchpoint": "whatsapp",
    "meta": {
        "namespace": "56cca706_4162_b9be_fc60_13623ff73b1e",
        "elementName": "your_car_is_ready",
        "language": "nl"
    }
}

The meta.language will default to the conversation- or organization language.

For more information, see the Sunshine Conversations and Facebook developer documentation for WhatsApp.

Contact our support team to have your WhatsApp template messages set up and approved for you.

Channel Transfer to Web

Channel transfers enable you to move a conversation with a contact to another channel, while preserving the conversation history and unifying the contact's identity in Web1on1. Changing channels can be used to authenticate contacts on your website, move the conversation to a channel that is less costly (eg. move away from SMS) and provide a better user experience by leveraging rich messaging features on modern channels.

By leveraging the auth code and link request APIs, links can be generated and sent to users to direct them to the channel of your choice. For example, communication with a contact often starts at over a channel such as email or SMS. Using an auth code, you can transfer such users' conversations over to the widget hosted on your website.

Invite by E-mail (Mailgun)

Request: POST /v2/conversations

{
    "organization": "5c7574c78ae07962b12e264c",
    "type": "contact",
    "contact": {
        "profile": {
            "name": "John Johnson",
            "email": "john.johnson@example.com"
        }
    },
    "messages": [{
        "role": "agent",
        "text": "Click the link to continue:",
        "touchpoint": "email",
        "actions": [{
            "text": "[continue conversation]",
            "type": "link",
            "uri": "https://yourwebsite.com/widget?id={authuser}&token={authtoken}"
        }]
    }]
}

Invite by SMS (Twilio)

If the organization has Twilio integrated, you can create a new conversation over SMS and invite the consumer towards the richer web channel:

{
    "organization": "5c7574c78ae07962b12e264c",
    "type": "contact",
    "contact": {
        "profile": {
            "name": "John Johnson",
            "telephone": "+31646280994"
        }
    },
    "messages": [
        {
            "role": "agent",
            "text": "Hey there. Time for a new appointment.",
            "touchpoint": "sms",
            "meta": {
                "SenderID": "Tims Truckshop"
            }
        },
        {
            "role": "agent",
            "text": "Click the link to continue:",
            "touchpoint": "sms",
            "delay": 5000,
            "actions": [{
                "text": "[continue conversation]",
                "type": "link",
                "uri": "http://yoursite.com/widget?id={authuser}&token={authtoken}"
            }],
            "meta": {
                "SenderID": "Tims Truckshop"
            }
        }
    ]
}

The meta.SenderID in this example is optional, and makes this a one-way notification SMS: the contact can not text back, but can only click on the link provided.

In both examples, the webwidget-link message can be added to existing conversations (by POSTing to /conversations/:id/messages).

Short URLs (cht.onl)

All web transfer links are shortened using our cht.onl URL Shortener, using the organization displayName as a subdomain. The original URL is stored in the action as longUri - after creating the conversation above, the message.actions property returned could look like this:

    "actions": [{
        "text": "[continue conversation]",
        "type": "link",
        "uri": "https://YourComany.cht.onl/l/YybXcHquS",
        "longUri": "http://yoursite.com/widget?id={authuser}&token={authtoken}"
    }]

For more details, see the API Reference.