Partner Addon - Api Chat Channel

Enhance your customer interactions by seamlessly integrating chat functionalities with our partner API. Whether you're automating responses or managing live agent interactions, setting up webhooks and sending various media types is straightforward. This guide will walk you through the steps to enable these features effectively.

When this partner addon is activated, your workspace can configure a webhook for the API chat channel.

Guide

Initial Configuration

1. Activate the partner addon, API Chat.

2. Configure the API chat webhook for your workspace using the partner API; ensure the webhook URL is verified.

3. Use the bot_url from the API chat webhook response to send messages from the bot user.

4. Refer to example payloads for different message types.

5. When the bot or agent replies, the message payload will be sent to the specified API chat webhook URL with a signature in the header.

Partner API for Managing Webhooks

Authenticate using your partner API key.

Retrieve Webhook

GET {{baseUrl}}/api/partner/workspace/{{workspace_id}}/apichat-webhook Request body: (empty)

Example response:

{ "status": "ok", "data": { "webhook_url": "", "webhook_verification_key": "VERIFICATION_TOKEN", "webhook_status": "verified", "bot_url": "{{unique_code_to_bot}}" } }

Configure Webhook

POST {{baseUrl}}/api/partner/workspace/{{workspace_id}}/set-apichat-webhook Request body:

{ "webhook_url": "", "webhook_verification_key": "VERIFICATION_TOKEN" } Note: Three parameters will be sent to your webhook URL via POST.

hub_mode: The value will be “subscribe".

hub_verify_token: This will match the "webhook_verification_key" from your request body, e.g., VERIFICATION_TOKEN.

hub_challenge: A random string, e.g., 205c40409f9bcdeb9e00614b442c5fdd.

Verify the verification key and return a text response with the content from the hub_challenge parameter as the body, e.g., 205c40409f9bcdeb9e00614b442c5fdd.

Example response (success):

{ "status": "ok", "data": { "webhook_url": "", "webhook_verification_key": "VERIFICATION_TOKEN", "webhook_status": "verified", "bot_url": "{{unique_code_to_bot}}" } }

Delete Webhook

DELETE {{baseUrl}}/api/partner/workspace/{{workspace_id}}/remove-apichat-webhook Request body: (empty)

Example response:

{ "status": "ok", "data": { "webhook_url": "", "webhook_verification_key": "", "webhook_status": "", "bot_url": "" } }

Workspace API for Sending Messages

Authenticate using your flow API key, which requires manage flow permission.

Send Text Message

POST {{unique_code_to_bot}} Request body:

{ "content": "{{TEXT MESSAGE}}", "message_type": "incoming", "sender": { "id": "{{UNIQUE BOT USER ID}}", "name": "{{BOT USER NAME}}", "email": "", "phone_number": "", "type": "contact" }, "conversation_id": 123, "event": "message_created" }

Send Button Payload

POST {{unique_code_to_bot}} Request body:

{ "content": "{{BUTTON TITLE}}", "message_type": "incoming", "sender": { "id": "{{UNIQUE BOT USER ID}}", "name": "{{BOT USER NAME}}", "email": "", "phone_number": "", "type": "contact" }, "conversation_id": 123, "event": "message_postback", "submitted_values": [ { "title": "{{BUTTON TITLE}}", "payload": "{{BUTTON PAYLOAD}}" } ] }

Send Image

POST {{unique_code_to_bot}} Request body:

{ "content": "", "message_type": "incoming", "sender": { "id": "{{UNIQUE BOT USER ID}}", "name": "{{BOT USER NAME}}", "email": "", "phone_number": "", "type": "contact" }, "conversation_id": 123, "event": "message_created", "attachments": [ { "file_type": "image", "data_url": "{{IMAGE URL}}" } ] }

Send Audio

POST {{unique_code_to_bot}} Request body:

{ "content": "", "message_type": "incoming", "sender": { "id": "{{UNIQUE BOT USER ID}}", "name": "{{BOT USER NAME}}", "email": "", "phone_number": "", "type": "contact" }, "conversation_id": 123, "event": "message_created", "attachments": [ { "file_type": "audio", "data_url": "{{AUDIO URL}}" } ] }

Send Video

POST {{unique_code_to_bot}} Request body:

{ "content": "", "message_type": "incoming", "sender": { "id": "{{UNIQUE BOT USER ID}}", "name": "{{BOT USER NAME}}", "email": "", "phone_number": "", "type": "contact" }, "conversation_id": 123, "event": "message_created", "attachments": [ { "file_type": "video", "data_url": "{{VIDEO URL}}" } ] }

Send File

POST {{unique_code_to_bot}} Request body:

{ "content": "", "message_type": "incoming", "sender": { "id": "{{UNIQUE BOT USER ID}}", "name": "{{BOT USER NAME}}", "email": "", "phone_number": "", "type": "contact" }, "conversation_id": 123, "event": "message_created", "attachments": [ { "file_type": "file", "data_url": "{{FILE URL}}" } ] }

Webhook Payload Details

When a bot or agent sends a message, your webhook URL will receive the message payload. For each request, check the following headers.

X-Hub-Signature-256: Used to verify the payload. x-flow-ns: The flow namespace for your bot. x-action: The webhook action type, which is "messages". Example PHP code to verify the payload signature:

$payload = request()->body(); $verification_key = "{{VERIFICATION_TOKEN}}"; $sign = 'sha256='.hash_hmac('sha256', $payload, $verification_key); // Ensure the header signature value matches request()->header('X-Hub-Signature-256') == $sign

Receive Text Message

{ "sender_id": "{{UNIQUE BOT USER ID}}", "conv_id": 123, "text": "{{TEXT MESSAGE}}", "type": "text", "message_type": "outgoing", "private": false }

Receive Button Template

{ "sender_id": "{{UNIQUE BOT USER ID}}", "conv_id": 123, "text": "{{TEXT MESSAGE}}", "type": "text", "message_type": "outgoing", "private": false, "content_type": "button_template", "content_attributes": { "text": "{{TEXT MESSAGE}}", "buttons": [ { "type": "postback", "title": "{{BUTTON TITLE}}", "payload": "{{BUTTON PAYLOAD}}" },{ "type": "postback", "title": "{{BUTTON TITLE}}", "payload": "{{BUTTON PAYLOAD}}" } ] } }

Receive Generic Template (Card/Carousel)

{ "sender_id": "{{UNIQUE BOT USER ID}}", "conv_id": 123, "text": "{{TEXT MESSAGE}}", "type": "text", "message_type": "outgoing", "private": false, "content_type": "generic_template", "content_attributes": { "ratio": "horizontal", "items": [ { "title": "{{TITLE}}", "image_url": "{{IMAGE URL}}", "item_url": null, "subtitle": "{{SUBTITLE}}", "default_action": null, "buttons": [ { "type": "postback", "title": "{{BUTTON TITLE}}", "payload": "{{BUTTON PAYLOAD}}" } ] }, { "title": "{{TITLE}}", "image_url": "{{IMAGE URL}}", "item_url": null, "subtitle": "{{SUBTITLE}}", "default_action": null, "buttons": [ { "type": "postback", "title": "{{BUTTON TITLE}}", "payload": "{{BUTTON PAYLOAD}}" } ] } ] } }

Receive Image Message

{ "sender_id": "{{UNIQUE BOT USER ID}}", "conv_id": 123, "url": "{{IMAGE URL}}", "type": "image", "message_type": "outgoing", "private": false }

Receive Audio Message

{ "sender_id": "{{UNIQUE BOT USER ID}}", "conv_id": 123, "url": "{{AUDIO URL}}", "type": "audio", "message_type": "outgoing", "private": false }

Receive Video Message

{ "sender_id": "{{UNIQUE BOT USER ID}}", "conv_id": 123, "url": "{{VIDEO URL}}", "type": "video", "message_type": "outgoing", "private": false }

Receive File Message

{ "sender_id": "{{UNIQUE BOT USER ID}}", "conv_id": 123, "url": "{{FILE URL}}", "type": "file", "message_type": "outgoing", "private": false }