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

```json
{
  "email": "cliente@example.com",
  "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

```json
{
  "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.

```json
{
  "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.