Your bot can the following actions using the Bot API v3.

• Respond to a message
• Pass conversation control
• Retrieve the entity (bot or agent) that has current control of the conversation
• Change the priority of the conversation
• Tag a message
• Change a conversation work queue
• Resolve a conversation
• Attach an internal note to the conversation
• Update CRM author attributes

Respond to a message

Respond to a message using a POST call the /bots/v3/respond endpoint, passing a JSON payload in the request body. The payload will differ depending on the type of response the bot sends.

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

• text
• references to external media
• a raw payload to the messaging provider (referred to as a passthrough)
• a postback
• a reply
• a listpicker (Apple Business Chat only)
• a custom extension payload (Apple Business Chat only)

See the /bots/v3/respond documentation to build your payload.

📘

Note

To ensure that emojis are delivered correctly, add charset=utf-8 to your header when using the /respondendpoint.

Pass conversation control to an agent

Your bot can pass conversation control to a Care agent using a POST request to /bots/v3/control. The request takes a control JSON payload as Body.

📘

Note

When processing a message from an external user, the Automation Framework automatically transfers control from BOT to AGENT if the current conversation control is undetermined or the conversation is owned by a BOT, but the currently registered bot is not in LIVE mode. When this handoff occurs, the conversation receives a handoff tag. See Bot handoffs and Bot Handoff tags to learn more different handoff tags and the circumstances that determine which handoff tag is assigned.

Retrieve the entity with control of the current conversation

Return the entity (BOT or AGENT) that currently controls the conversation with a GET request to
/bots/v3/control/network/{networkKey}/externalId/{externalId}/author/{authorId}. Specify the networkKey (the source channel) and externalId (the external identifier) associated with the bot and the authorId of the conversation author as path parameters.

The type attribute of the owner object in the response will be either AGENT or BOT.

Change the priority of the conversation

Change the conversation priority with a PUT request to /bots/v3/priority. The request takes a priority JSON payload as Body.

Tag a message

Tag a specific message with an existing Care tag ID using a PUT request to /bots/v3/tag. The call takes a tag JSON payload as Body. You may apply one or more tag IDs in an integer array.

Change a conversation work queue

Your bot can move a conversation to a different work queue with a PUT request to /bots/v3/workqueue. The endpoint requires a workqueue payload as Body.

Resolve a conversation

Have the bot mark a conversation as resolved with a PUT request to the /bots/v3/resolve. Care will close the corresponding conversation as resolved in the Response app. The endpoint takes a resolve JSON payload as Body. You may add a comment in the payload about the case resolution to store as an internal note visible in the Response case history.

Attach an internal note to the conversation

Your bot can add an internal note to a conversation with a PUT request to /bots/v3/note. The endpoint takes a note JSON payload as Body. The note will appear in the Response case history.

Update CRM author attributes

Your bot can update author CRM attributes with a PUT request to bots/v3/author. The endpoint takes an author JSON payload as Body.