Como criar uma caixa de entrada de API

Use este guia para criar uma caixa de entrada de API na IAra e integrar conversas vindas de um sistema próprio.

Quando usar

Use caixa de entrada de API quando você quer conectar um canal que não existe nativamente na IAra, como um app próprio, portal do cliente, plataforma vertical ou experiência de chat dentro do seu produto.

Criar a caixa de entrada

1. Acesse Configurações > Caixas de entrada.
2. Clique em Adicionar caixa de entrada.
3. Escolha o canal API.
4. Informe nome do canal e URL de callback.
5. Adicione agentes ou times que vão atender as conversas.
6. Salve e copie os identificadores exibidos na configuração.

Fluxo para enviar mensagem

O fluxo técnico costuma ter três etapas:

1. Criar ou localizar contato.
2. Criar conversa usando o source_id do contato naquela caixa.
3. Criar mensagem na conversa.

As APIs exigem api_access_token no cabeçalho da requisição.

Exemplo de contato criado

{
  "email": "[email protected]",
  "name": "Maria Souza",
  "phone_number": "+5511999999999",
  "additional_attributes": {},
  "contact_inboxes": [
    {
      "source_id": "source-id-do-contato",
      "inbox": {
        "id": 123,
        "name": "Canal API",
        "channel_type": "Channel::Api"
      }
    }
  ],
  "id": 456,
  "availability_status": "offline"
}

Use o source_id para iniciar a conversa.

Exemplo de mensagem criada

{
  "id": 789,
  "content": "Mensagem recebida pelo canal API",
  "inbox_id": 123,
  "conversation_id": 456,
  "message_type": 0,
  "content_type": "text",
  "content_attributes": {},
  "private": false,
  "sender": {
    "id": 456,
    "name": "Maria Souza",
    "type": "contact"
  }
}

Receber mensagens via callback

Quando uma nova mensagem for criada no canal API, a IAra envia um POST para a URL de callback configurada.

{
  "event": "message_created",
  "id": 789,
  "content": "Mensagem recebida pelo canal API",
  "message_type": "incoming",
  "content_type": "text",
  "content_attributes": {},
  "sender": {
    "id": 456,
    "name": "Maria Souza",
    "type": "contact"
  },
  "inbox": {
    "id": 123,
    "name": "Canal API"
  },
  "conversation": {
    "id": 456,
    "inbox_id": 123,
    "status": "open"
  },
  "account": {
    "id": 59,
    "name": "Minha conta"
  }
}

Boas práticas

• Salve source_id no seu sistema.
• Use identificadores estáveis para contatos.
• Valide assinatura de webhook quando disponível.
• Registre logs de envio e recebimento.
• Evite criar contato duplicado para o mesmo cliente.