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.

Business Initiated Conversations

Usually, in Web1on1, conversations are initiated by the end-user (the consumer, called "contact"). Whether they are sending an email to your support address, reaching out on Facebook Messenger, or contacting you via WhatsApp, the typical flow requires the contact to message first. However, in some circumstances it is necessary for the business to proactively reach out to a new contact and engage them in a conversation.

Each contact is linked to exactly one conversation. When creating a new conversation through the API, a contact record is also created for the provided contact.profile. In addition, at least one outbound message must be provided, which will be sent to the contact immediately.

Create a new Contact Conversation (Email or SMS)

To create a conversation representing a consumer, provide a contact object, and set the conversation.type to contact. You must also specify a profile with at least an identifier (email or telephone). An error will be returned if the contact already exists.

Set message.role to:

  • bot for bot-to-agent communication,
  • agent to talk to the consumer, and
  • contact to represent a consumer message.

Bots talking to consumers would do so with message.role "agent".

Request: POST /v2/conversations

{
    "organization": "aaa111111111111111111222",
    "type": "contact",
    "contact": {
        "profile": {
            "name": "John Johnson",
            "telephone": "+31646280994"
        }
    },
    "messages": [
        {
            "text": "Hey there.",
            "touchpoint": "sms",
            "role": "agent"
        },
        {
            "text": "How are you?",
            "role": "agent"
        },
        {
            "text": "/leave",
            "type": "command",
            "delay": 3000
        }
    ]
}

This creates the contact record, and processes the messages:

  • The first message needs to provide a touchpoint, as a conversation.touchpoint is not specified. It will link the contact through a Sunshine Conversations appUser, and the contact will receive the message via Twilio SMS. The agent (no message.user specified, so defaulting to the API key owner) accepts the conversation as a result of the message, so will automatically join the conversation with participant flags 'active' set. The conversation status is set to 'active'.
  • The second message will use the now active SMS channel to send a second message the contact. These first two messages were sent as an SMS to John's mobile phone.
  • The third message makes the bot leave the conversation; this will close the conversation and trigger channel notifications when new contact messages come in. By using a short delay we make sure the messages are processed in a next processing iteration/tick, after the previous messages.

Response: 201 CREATED

{
    "organization": "aaa111111111111111111222",
    "orgPath": "aaa111111111111111111111#aaa111111111111111111222",
    "name": "Fimlebick Fastfuzz",
    "type": "contact",
    "slug": "HJIGT96F7",
    "url": "https://app.web1on1.chat/c/HJIGT96F7",
    "status": "queued",
    "contact": "5bb01d0dd99faf11a3f4a36d",
    "participants": [
        {
            "updatedAt": "2018-09-30T00:47:19.872Z",
            "createdAt": "2018-09-30T00:47:09.868Z",
            "name": "testbot",
            "avatar": "https://storage.googleapis.com/cs2-uploads/avatars/ca6e1762-988e-4cbc-becb-ad952b6df9a4.png",
            "user": "aaa000000000000000000111",
            "unreadCount": 1,
            "inbox": false,
            "accepted": false,
            "active": false,
            "role": "agent"
        }
    ],
    "messages": [
        "5bb01d0dd99faf11a3f4a36e",
        "5bb01d0dd99faf11a3f4a36f",
        "5bb01d0fd99faf11a3f4a374"
    ],
    "channels": [
        "5b99be371951542b5f47eeb4"
    ],
    "channelsOffline": [
        "5b9ae5460a13a54282ca20d0"
    ],
    "touchpoints": {
        "sms": {
            "services": [
                "5b6f8a73623a375f28a5380c"
            ],
            "selected": true
        }
    },
    "forms": [],
    "results": [],
    "createdBy": "aaa000000000000000000111",
    "updatedAt": "2018-09-30T00:47:20.122Z",
    "createdAt": "2018-09-30T00:47:09.787Z",
    "id": "5bb01d0dd99faf11a3f4a36c"
}

Create a new Contact Conversation (WhatsApp)

If you know for a fact that the new contact has a WhatsApp account tied to his/her telephone number, it's possible to start the conversation with the customer over WhatsApp. The initial message (and any message therafter, until the contact replies) must be an approved WhatsApp Template message.

Request: POST /v2/conversations

{
    "organization": "5bad2f12e91d2c331be33364",
    "type": "contact",
    "contact": {
        "profile": {
            "name": "John Johnson",
            "telephone": "+31646280994"
        }
    },
    "messages": [{
        "role": "agent",
        "text": "Your car is ready to be picked up!",
        "touchpoint": "whatsapp",
        "meta": {
            "language": "nl",
            "namespace": "56cca706_4162_b9be_fc60_13623ff73b1e",
            "elementName": "your_car_is_ready"
        }
    }],
}

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.