Developer DiscussionDeveloper BlogAtlas
API Reference

Respond to incoming message (bot to channel)

post https://api.app.lithium.com/bots/v3/respond

Respond to an incoming message (bot to channel)

Details

Respond to an incoming message using a POST call the /respond endpoint.

📘

Note

Include charset=utf-8 as seen in the curl example to the right to ensure that emojis are processed correctly.

A bot can respond to an incoming message in several ways:

  • text
  • typing start and stop indicators letting the recipient know new messages are in progress
  • a listpicker (Apple Business Chat only)
  • references to external media
  • a raw payload to the messaging provider (referred to as a passthrough)
  • a postback
  • a reply
  • a custom extension payload (Apple Business Chat only)

📘

Note

A raw passthrough and a listpicker cannot be set in the same message payload.

The typing_start and typing_stop indicators can only be sent in Brand Messenger, Facebook, Google Business Messages, and Apple Business Chat.

📘

Note

A bot attempting to respond to a conversation it doesn’t own will receive a 403 Forbidden response.

We've included examples of JSON payloads used to send a message, start the typing indicator, and stop the typing indicator. The payload fields vary depending on the type of response sent.

{  
  "coordinate":<coordinate-object>,
  "text":"<response-body-text>",
  "type":"message",
  "author":{  
    "id":"<network-author-id>",
    "fullName":"<author-name>"
  },
  "list":<list-definition>,
  "payload":"<raw passthrough payload>",
  "media":[
    {
      <media payload>
    }
  ],
  "richContent":<richContent-definition>
}

{
  "author":{
     "id":"adf9as8df9sfi",
     "fullName":"fullname"
  },
  "coordinate":{
     "companyKey":"company",
     "networkKey":"smooch",
     "externalId":"sf8u123jfasdf123",
     "botId":"botId",
     "scope":"PRIVATE"
  },
  "type":"typing_start"
}

{
  "author":{
     "id":"adf9as8df9sfi",
     "fullName":"fullname"
  },
  "coordinate":{
     "companyKey":"company",
     "networkKey":"smooch",
     "externalId":"sf8u123jfasdf123",
     "botId":"botId",
     "scope":"PRIVATE"
  },
  "type":"typing_stop"
}

📘

Note

The typing_start and typing_stop payloads must include the author, coordinate, and type fields. The companyKey in the endpoint must also match companyKey in the coordinate.

Outgoing Message JSON payload fields

FieldDescription
actionsAn Actions object. Used with postback and reply payloads. The actions object represents structured actions that the user can take. The payload field is the payload sent to the bot on the activation of a reply or quick reply button.


Example postback
"actions":[ { "type":"postback", "payload":"DEVELOPER_DEFINED_PAYLOAD-001", "text":"A good way to keep h..." } ],

Example reply
"actions":[ { "type":"reply", "payload":"POSTBACK_PAYLOAD-QR-01" } ],
authorRequired. An Author object representing the message author on the source channel. Included with all outgoing message payloads.****
coordinateRequired. A Coordinate object. This is object contains details about the bot and the message in context. Included with all outgoing message payloads.
listOptional. A list definition for a listpicker. Included with listpicker payloads.

Note: list cannot be set in a request payload that includes the a payload, media, or richContent field.

Example
"list":{ "requestMessage":{ "title":"request message title", "subtitle":"request message subtitle", "media":<optional image media payload>, "style": <size of the preview image:LARGE, SMALL, ICON. Default SMALL> }, "responseMessage":{ "title":"reply message title", "subtitle":"reply message title", "media":<optional image media payload>, "style": <size of the preview image:LARGE, SMALL, ICON. Default SMALL> }, "sections":[ { "id":"0", "title":"Choose a beer", "multipleSelection":true, "choices":[ { "id":"beer1", "message":{ "title":"This beer", "subtitle":"(🍺)", "media":<optional image media payload> } } ] } ] }
mediaOptional. A list with exactly one reference to external media.

Note: media cannot be set in a request payload that includes a list, richContent, or payload field.

Example
"media":[ { "url":"https://pics.example.com/some_cool_picture.jpg", "mediaType":"IMAGE" } ],
richContentOptional. For networks that support rich content (also known as rich links), this structure references external rich content. Use the text field as a fallback in case the network doesn’t support rich content.

Note: richContent cannot be set in a request payload that includes a list, payload, or media field.

Example
"richContent":{ "mediaType":"IMAGE", "url":"https://www.example.com/article.html", "title":"some title", "mediaUrl":"https://www4.example.com/cool_pic_to_display.jpg", "mimeType":"image/jpeg" },
ownerThe entity that has current control of the conversation. Included with postback and reply payloads.

Note: Currently, the Automation Framework defaults to the bot as owner for any new conversation
payloadOptional. A stringified JSON raw payload to pass through to a messaging provider. Used with raw passthrough and custom Apple Business Chat extension payloads. The format is provider-specific, and you should refer to the provider's documentation.

Note: Cannot be set in a request payload that uses includes the list field.

Example raw passthrough payload
"payload": "{\"text\":\"Here is a quick reply!\",\"quick_replies\":[{\"content_type\":\"text\",\"title\":\"Search\",\"payload\":\"<POSTBACK_PAYLOAD>\",\"image_url\":\"http://example.com/img/red.png\"},{\"content_type\":\"location\"}]}",

Example custom extension payload
"payload": "{\"appId\":\"123456789\",\"appName\":\"Lithium Extension app name\",\"URL\":\"?type=firstName\",\"bid\":\"com.apple.messages.MSMessageExtensionBalloonPlugin:appleDevTeamID:com.lithium.Ecohaus.EcohausExtension\",\"receivedMessage\":{\"title\":\"Lithium Extension\"},\"useLiveLayout\":true}"
processSynchronouslyOptional. If set to true, you will receive either a 200 OK message in the event sending the response is successful, or you will receive an error code with details about a failure.

See the Response codes and the processSynchronously field section for more details.

publishedTSThe timestamp of when the message was published in epoch milliseconds. Used with postback and reply payloads.
receivedTSThe timestamp of when Khoros Care processed and stored the message (in epoch milliseconds). Used with postback and reply payloads.
textOptional. Body text of the outgoing message. Included in text, listpicker, and reply payloads.

Example
"text": "Message text here",
typeAlways message when sending a message. Included with all outgoing message payloads.

Typing indicators are started with typing_start and stopped with typing_stop. Sending a message does not automatically stop the typing indicator.

For structured messages payload in Brand Messenger, see Structured Messages Payload.

Response codes and the processSynchronously field

This processSynchronously field instructs the Automation Framework to publish the response synchronously and return details about the publish attempt directly to the bot. This enables the bot to immediately receive a response about the actual success/failure of the message, bypassing any need to poll another endpoint to determine the status of the request.

The result, if set to true, is a 200 OK response (see example in the responses section of this page) that includes a requestState field indicating that the message has been successfully sent.

In the event that the message fails to send, an error code is returned indicating the cause of the failure.

If this field is not present, or if it set to false, then a standard 202 response is sent.

Language