Para Desenvolvedores/Canal por API

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.

2026-08-18

Canal por API

YouTube

Atenção

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

💴 Pagamento do Complemento

Esse complemento exige um setup de valor único, que libera uma chave de API para autenticar o cadastro de webhooks em qualquer número de workspaces. Cada sistema a ser integrado exige um setup próprio. O valor vigente é informado pelo suporte na contratação. Exemplos:

Se você quiser integrar um sistema a diversas workspaces, haverá apenas uma cobrança de setup.
Se você tiver 2 sistemas para integrar, serão 2 cobranças de setup, independentemente do número de workspaces.

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

Dica

Envie o comprovante de pagamento para o Suporte do NicoChat para realizarmos o setup.

\uD83D\uDCD8 Instruções

- Configuração inicial

Habilitar o complemento de parceiro com o Suporte do NicoChat, Api Chat. Será fornecida uma chave API para configurar o Webhook. A autenticação será por Bearer Auth.
Configurar o webhook da Api Chat para a workspace através da API 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 contato.
Verifique o payload de exemplo para diferentes tipos de mensagens.
Quando o fluxo 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 registro de webhook.

Nota

Atualização 24/04/2025: Não será mais necessário enviar o “Id da Workspace” e o “Email” em nenhuma requisição. Apenas a Chave API do NicoChat.

- Get webhook

texto

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

Corpo da requisição:

texto

{
    "ChaveApi": "{{Chave API do NicoChat}}"
}

Exemplo de resposta:

texto

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

texto

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

Corpo da requisição:

texto

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

Atenção

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):

texto

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

texto

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

Corpo da requisição:

texto

{
    "ChaveApi": "{{Chave API do NicoChat}}"
}

Exemplo de resposta (sucesso):

texto

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

\uD83D\uDCCB API da Workspace para enviar mensagens.

Você precisa usar a Chave API do seu fluxo para autenticação, o que requer a permissão Gerenciar Fluxo.

- Send Text Message

texto

POST https://bot.dfktv2.com/api/apichat/{{unique_code_to_bot}}

Corpo da requisição:

texto

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

texto

POST https://bot.dfktv2.com/api/apichat/{{unique_code_to_bot}}

Corpo da requisição:

texto

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

texto

POST https://bot.dfktv2.com/api/apichat/{{unique_code_to_bot}}

Corpo da requisição:

texto

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

texto

POST https://bot.dfktv2.com/api/apichat/{{unique_code_to_bot}}

Corpo da requisição:

texto

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

texto

POST https://bot.dfktv2.com/api/apichat/{{unique_code_to_bot}}

Corpo da requisição:

texto

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

texto

POST https://bot.dfktv2.com/api/apichat/{{unique_code_to_bot}}

Corpo da requisição:

texto

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

texto

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.

texto

$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

texto

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

- Receive Button Template

texto

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

texto

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

texto

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

- Receive Audio Message

texto

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

- Receive Video Message

texto

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

- Receive File Message

texto

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