API Chat Channel

Integrating external users into Flexito OmniAI's live chat system enhances communication by allowing seamless interactions with agents. This integration ensures all user queries are managed efficiently from a single platform, providing a streamlined experience for both agents and users.

Enabling this partner addon allows the client's workspace to configure a webhook for the API chat channel.

This addon allows users from external sources to be integrated into Flexito OmniAI's live chat system. Once integrated, these users can have real-time conversations with agents, similar to regular communication channels. This provides a unified messaging experience, enabling agents to handle and respond to all user queries from one platform.

Please contact Flexito OmniAI support for assistance with this channel.

Instructions Initial setup

1. Enable the partner addon for API Chat.

2. Set the API chat webhook for your workspace using the partner API. The webhook URL must be verified.

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

4. Refer to the example payload for different message types.

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

Partner API for Webhook Management

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 value matches the "webhook_verification_key" from your request body. For example, it will be VERIFICATION_TOKEN.

hub_challenge: This will be a random string, e.g., 205c40409f9bcdeb9e00614b442c5fdd.

You must 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}}" } }

Remove 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.

The API Key used must be specific to the workspace and bot. The Partner API master key will not work here.

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: Represents the flow namespace for your bot x-action: Indicates the webhook action type, with the value "messages" Sample 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 }