Canal por API

É possível conectar um canal por API no NicoChat! Isso possibilita utilizar o NicoChat para automatizar as interações de um chat interno do seu Sistema. A Integração envia e recebe mensagens utilizando o OmniChannel da Workspace.

Esse é um complemento pago, caso tenha dúvidas entre em contato com o Suporte.

💴 Pagamento do Complemento

Esse complemento exige um setup no valor único de R$ 750,00. Esse set-up liberará uma chave API para fazer a autenticação do cadastro de webhooks em qualquer número de workspaces. Cada Sistema a ser integrado irá requerer um setup. Exemplos:

Se você quiser integrar um sistema a diversas workspaces irá haver apenas uma cobrança de setup.
Se você tiver 2 sistemas que deseja integrar, irá requerer 2 cobranças de setups, independente do numero de workspaces.

O Link de Pagamento do setup é o seguinte: https://buy.stripe.com/6oE3fgexL3mEb6g00i

Envie o comprovante de pagamento para o Suporte do NicoChat para realizarmos o set-up

\uD83D\uDCD8 Instruções

- Configuração inicial

Habilitar o complemento de parceiro com o Suporte do NicoChat, Api Chat. Será oferecido uma chave API para configuração do Webhook. A Autenticação será por Bearer Auth
Configurar o webhook da Api Chat para o workspace através da API do oferecida pelo suporte. A URL do webhook precisa ser verificada.
O bot_url, retornado na resposta da configuração do webhook da Api Chat, será usado para enviar mensagens do usuário do bot.
Verifique o payload de exemplo para diferentes tipos de mensagens.
Quando o bot ou o agente responder, o payload da mensagem será enviado para a URL do webhook da Api Chat fornecida, com uma assinatura incluída no cabeçalho

Você receberá uma Chave API para fazer as requisições de requisições de registo de webhook.

- Get webhook

POST {{baseUrl}}?action=get-webhook

Request body:

{
    "workspace": {{workspace_id}},
    "email": "{{workspace_email}}",
    "ChaveApi": "{{Chave API do NicoChat}}"
}

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}}?action=set-webhook

Request body:

{
    "workspace": {{workspace_id}},
    "email": "{{workspace_email}}",
    "ChaveApi": "{{Chave API do NicoChat}}",
    "webhook_url": "https://your-webhook-url/",
    "webhook_verification_key": "VERIFICATION_TOKEN"
}

Nota: Três parâmetros serão enviados para a URL do seu webhook via POST para verificação:

hub_mode: O valor será “subscribe"

hub_verify_token : O valor será o mesmo fornecido no corpo da sua requisição como "webhook_verification_key", o exemplo acima foi VERIFICATION_TOKEN

hub_challenge: O valor será uma string aleatória, por exemplo: 205c40409f9bcdeb9e00614b442c5fdd

Você precisa verificar a chave de verificação e retornar a resposta com o conteúdo do parâmetro hub_challenge no corpo da resposta. Exemplo: 205c40409f9bcdeb9e00614b442c5fdd

Exemplo de resposta (sucesso):

{
    "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

POST {{baseUrl}}?action=delete-webhook

Request body:

{
    "workspace": {{workspace_id}},
    "email": "{{workspace_email}}",
    "ChaveApi": "{{Chave API do NicoChat}}"
}

Exemplo de resposta (sucesso):

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

\uD83D\uDCCB API do Workspace para enviar mensagens.

Você precisa usar a chave de API do seu fluxo para autenticação, o que requer a permissão de gerenciar fluxo.

- 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

Quando o bot ou agente envia uma mensagem, a URL do seu webhook receberá o payload da mensagem. Para cada requisição, você pode verificar os seguintes 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"

Código PHP de exemplo para verificar a assinatura do payload.

$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
}