API Chat Channel

When this partner addon is enabled, the client’s workspace will be able to set webhook for api chat channel.

Please reach out to UChat support for this channel.

\uD83D\uDCD8 Instructions

Initial setup

Enable partner addon, Api Chat
set api chat webhook for workspace through partner api, the webhook url need to be verified
bot_url from the set api chat webhook response, will be used to send messages from bot user
check example payload for different type of messages
when bot reply or agent reply, the message payload will be sent to provided api chat webhook url with signature in the header

\uD83D\uDCCB Partner Api to get/set/remove webhook

You need to use your partner api key for authentication

- Get webhook

GET {{baseUrl}}/api/partner/workspace/{{workspace_id}}/apichat-webhook

Request body: (empty)

Sample response,

{
    "status": "ok",
    "data": {
        "webhook_url": "https://your-webhook-url/",
        "webhook_verification_key": "VERIFICATION_TOKEN",
        "webhook_status": "verified",
        "bot_url": "https://bot.dfktv2.com/api/apichat/{{unique_code_to_bot}}"
    }
}

- Set webhook

POST {{baseUrl}}/api/partner/workspace/{{workspace_id}}/apichat-webhook

Request body:

{
    "webhook_url": "https://your-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 : the value will be the same value from your request body “webhook_verification_key“, as the sample above, the value will be VERIFICATION_TOKEN

hub_challenge: the value will be random string, e.g. 205c40409f9bcdeb9e00614b442c5fdd

You need to verify the verification key and return the text response output with the content from parameter hub_challenge as body, e.g. 205c40409f9bcdeb9e00614b442c5fdd

Sample response, (success)

{
    "status": "ok",
    "data": {
        "webhook_url": "https://your-webhook-url/",
        "webhook_verification_key": "VERIFICATION_TOKEN",
        "webhook_status": "verified",
        "bot_url": "https://bot.dfktv2.com/api/apichat/{{unique_code_to_bot}}"
    }
}

- Remove webhook

DELETE {{baseUrl}}/api/partner/workspace/{{workspace_id}}/apichat-webhook

Request body: (empty)

Sample response,

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

\uD83D\uDCCB Workspace Api to send messages

You need to use your flow api key for authentication, requires manage flow permission

- Send Text Message

POST https://bot.dfktv2.com/api/apichat/{{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 https://bot.dfktv2.com/api/apichat/{{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 https://bot.dfktv2.com/api/apichat/{{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 https://bot.dfktv2.com/api/apichat/{{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 https://bot.dfktv2.com/api/apichat/{{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 https://bot.dfktv2.com/api/apichat/{{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}}"
        }
    ]
}

\uD83D\uDCCB Webhook payload

When the bot or agent send a message, your webhook url l receive the message payload. For each request, you can check the following headers.

X-Hub-Signature-256: this is used to verify the payload
x-flow-ns: this is the flow ns for your bot
x-action: this is the webhook action type, the value is "messages"

Sample php code to verify the payload signature

$payload = request()->body();
$verification_key = "{{VERIFICATION_TOKEN}}";
$sign = 'sha256='.hash_hmac('sha256', $payload, $verification_key);
//you need to check the header signature value is matched
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
}