Referencia da API

A API do Dialogy e organizada em torno de REST. Nossa API tem URLs orientadas a recursos, aceita corpos de solicitacao codificados em formulario, retorna respostas em JSON e usa codigos HTTP padrao.

Base URL: https://dialogy.klyraai.com.br

Mensagens Recurso

O recurso de mensagens permite que voce envie e receba mensagens atraves de varios canais.

Endpoints

POST/messages

Envia uma nova mensagem para um contato.

GET/messages

Lista todas as mensagens enviadas e recebidas.

GET/messages/:id

Recupera os detalhes de uma mensagem especifica.

Exemplo de Requisicao

{
  "to": "+5511999999999",
  "channel": "whatsapp",
  "content": {
    "type": "text",
    "text": "Ola! Como posso ajudar voce hoje?"
  }
}

Exemplo de Resposta

{
  "id": "msg_123456789",
  "status": "queued",
  "created_at": "2023-10-27T10:00:00Z"
}

Templates por Agente WhatsApp

Use este endpoint para enviar templates aprovados da Meta pelo WhatsApp Cloud API conectado na Dialogy. A Dialogy valida o token do agente, resolve o workspace do agente, localiza ou cria o contato/chat e repassa os componentes para a Evolution API.

Endpoint

POST/api/agent/templates/send

Envia um template aprovado pelo WhatsApp usando uma instancia conectada ao workspace do agente.

Autenticacao

Envie o token de um system agent ativo no header Authorization. O token precisa pertencer ao mesmo workspace da instancia informada.

Authorization: Bearer TOKEN_DO_SYSTEM_AGENT

Corpo da Requisicao

CampoTipoObrigatorioDescricao
numberidstringSimNumero do destinatario com DDI e DDD. Exemplo: 5561995215930.
instanceNamestringSimNome da instancia WhatsApp na Dialogy/Evolution. Exemplo: zap7.
namestringSimNome exato do template aprovado na Meta.
languagestringSimCodigo do idioma do template. Exemplo: pt_BR.
componentsarraySimComponentes do template no mesmo formato aceito pela Evolution API: header, body e button.

Template simples com variaveis no BODY

Para templates com variaveis posicionais, envie os parametros na mesma ordem dos marcadores do template: {{1}}, {{2}} e assim por diante.

{
  "numberid": "5561995215930",
  "instanceName": "zap7",
  "name": "nome_do_template_aprovado",
  "language": "pt_BR",
  "components": [
    {
      "type": "body",
      "parameters": [
        { "type": "text", "text": "Primeira variavel" },
        { "type": "text", "text": "Segunda variavel" }
      ]
    }
  ]
}

Template ORDER_DETAILS com Pix

Templates com header de imagem precisam receber o componente header com uma URL publica HTTPS. Para botao de detalhes do pedido, use sub_type: order_details e parametro type: action.

curl --location 'https://dialogy.klyraai.com.br/api/agent/templates/send' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer TOKEN_DO_SYSTEM_AGENT' \
  --data '{
    "numberid": "5561995215930",
    "instanceName": "zap7",
    "name": "fatura_velpro_clientes_2026_maio",
    "language": "pt_BR",
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "https://velpro.net.br/uploads/site-assets/public/company-logo.png?t=1770142936029"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Nome do Cliente" },
          { "type": "text", "text": "123456" },
          { "type": "text", "text": "31/05/2026" },
          { "type": "text", "text": "99,90" },
          { "type": "text", "text": "78910" }
        ]
      },
      {
        "type": "button",
        "sub_type": "order_details",
        "index": 0,
        "parameters": [
          {
            "type": "action",
            "action": {
              "order_details": {
                "reference_id": "fatura_123456_78910",
                "type": "digital-goods",
                "payment_type": "br",
                "payment_settings": [
                  {
                    "type": "pix_dynamic_code",
                    "pix_dynamic_code": {
                      "code": "00020101021226860014br.gov.bcb.pix...",
                      "merchant_name": "VELPRO TELECOM",
                      "key": "00000000000000",
                      "key_type": "CNPJ"
                    }
                  }
                ],
                "currency": "BRL",
                "total_amount": {
                  "value": 9990,
                  "offset": 100
                },
                "order": {
                  "status": "pending",
                  "items": [
                    {
                      "retailer_id": "fatura_123456",
                      "name": "Fatura 123456",
                      "amount": {
                        "value": 9990,
                        "offset": 100
                      },
                      "quantity": 1
                    }
                  ],
                  "subtotal": {
                    "value": 9990,
                    "offset": 100
                  },
                  "tax": {
                    "value": 0,
                    "offset": 100
                  }
                }
              }
            }
          }
        ]
      }
    ]
  }'

Resposta

Uma resposta de sucesso indica que a requisicao foi aceita pela Evolution/WhatsApp. O status inicial pode vir como PENDING; a entrega final depende dos eventos de status do provedor.

{
  "success": true,
  "message": "Template sent successfully.",
  "apiResponse": {
    "key": {
      "fromMe": true,
      "id": "wamid...",
      "remoteJid": "5561995215930@s.whatsapp.net"
    },
    "status": "PENDING"
  }
}

Cuidados importantes

  • O template precisa estar aprovado na Meta e disponivel na instancia informada.
  • Se o template tiver HEADER IMAGE, o envio deve incluir um header com imagem valida; caso contrario a Meta retorna erro de formato.
  • Valores monetarios em order_details usam centavos com offset 100. Exemplo: R$ 99,90 deve ser enviado como value 9990 e offset 100.
  • A chave Pix e o codigo Pix devem ser reais no ambiente de producao. Placeholders podem gerar falhas ou botoes sem acao util.

Contatos Recurso

Gerencie sua base de contatos e seus metadados.

Endpoints

POST/contacts

Cria um novo contato.

GET/contacts

Lista todos os contatos.

Referencia da API | Dialogy