Caixas de Entrada (Inboxes)

Inboxes representam canais de atendimento habilitados, como WhatsApp, Web Chat e outros. Cada inbox pode ter agentes atribuídos e configurações específicas do canal.

GET/api/v1/accounts/{account_id}/inboxes

Lista todas as caixas de entrada (inboxes) da conta.

Parâmetros

Nome	Tipo	Obrigatorio	Descricao
`account_id`(path)	`integer`	Sim	ID numérico da conta

curl -s "https://chat.seudominio.com/api/v1/accounts/1/inboxes" \
  -H "api_access_token: YOUR_TOKEN" | jq .

200Lista de inboxes

json

{
  "payload": [
    {
      "id": 1,
      "name": "WhatsApp Suporte",
      "channel_type": "Channel::Whatsapp",
      "phone_number": "+5511999999999",
      "greeting_enabled": true,
      "greeting_message": "Ola! Como posso ajudar?"
    },
    {
      "id": 2,
      "name": "Widget Site",
      "channel_type": "Channel::WebWidget",
      "website_url": "https://empresa.com"
    }
  ]
}

GET/api/v1/accounts/{account_id}/inboxes/{id}

Retorna os detalhes de um inbox específico.

Parâmetros

Nome	Tipo	Obrigatorio	Descricao
`account_id`(path)	`integer`	Sim	ID numérico da conta
`id`(path)	`integer`	Sim	ID do inbox

bash

curl -s "https://chat.seudominio.com/api/v1/accounts/1/inboxes/1" \
  -H "api_access_token: YOUR_TOKEN" | jq .

POST/api/v1/accounts/{account_id}/inboxes

Cria um novo inbox (canal de atendimento).

Body

Nome	Tipo	Obrigatorio	Descricao
`name`	`string`	Sim	Nome do inbox
`channel`	`object`	Sim	Configuração do canal (varia por tipo)
`greeting_enabled`	`boolean`	Nao	Habilitar saudação automática
`greeting_message`	`string`	Nao	Mensagem de saudação

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/inboxes" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Widget do Site",
    "channel": {
      "type": "web_widget",
      "website_url": "https://meusite.com"
    },
    "greeting_enabled": true,
    "greeting_message": "Ola! Em que posso ajudar?"
  }'

PATCH/api/v1/accounts/{account_id}/inboxes/{id}

Atualiza configurações de um inbox existente.

Body

Nome	Tipo	Obrigatorio	Descricao
`name`	`string`	Nao	Nome do inbox
`enable_auto_assignment`	`boolean`	Nao	Auto-atribuição de conversas
`greeting_enabled`	`boolean`	Nao	Saudação automática
`greeting_message`	`string`	Nao	Mensagem de saudação
`out_of_office_message`	`string`	Nao	Mensagem fora do horário

bash

curl -X PATCH "https://chat.seudominio.com/api/v1/accounts/1/inboxes/1" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "greeting_message": "Ola! Bem-vindo ao suporte.",
    "enable_auto_assignment": true
  }'

DELETE/api/v1/accounts/{account_id}/inboxes/{id}

Remove um inbox e todas as conversas associadas.

bash

curl -X DELETE "https://chat.seudominio.com/api/v1/accounts/1/inboxes/1" \
  -H "api_access_token: YOUR_TOKEN"

Atenção

Deletar um inbox remove permanentemente todas as conversas e mensagens associadas.

Agentes do Inbox

GET/api/v1/accounts/{account_id}/inbox_members/{inbox_id}

Lista os agentes atribuídos a um inbox.

200Lista de agentes

json

{
  "payload": [
    { "id": 1, "name": "Maria", "role": "agent", "availability_status": "online" },
    { "id": 2, "name": "Pedro", "role": "agent", "availability_status": "offline" }
  ]
}

POST/api/v1/accounts/{account_id}/inbox_members

Adiciona agentes a um inbox (apenas adiciona — não remove nem substitui; não há DELETE de inbox_members na API).

Body

Nome	Tipo	Obrigatorio	Descricao
`inbox_id`	`integer`	Sim	ID do inbox
`user_ids`	`array`	Sim	Array de IDs dos agentes

bash

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/inbox_members" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "inbox_id": 1, "user_ids": [1, 2, 3] }'

Tipos de Canal

Canal	channel_type	Descrição
Web Widget	`Channel::WebWidget`	Chat ao vivo no site
WhatsApp	`Channel::Whatsapp`	WhatsApp Business API
API	`Channel::Api`	Canal via API para integrações customizadas
Facebook	`Channel::FacebookPage`	Página do Facebook Messenger
Instagram	`Channel::Instagram`	DMs do Instagram
SMS	`Channel::Sms`	Mensagens SMS via Bandwidth (o canal Twilio SMS é Channel::TwilioSms)
Telegram	`Channel::Telegram`	Bot do Telegram
LINE	`Channel::Line`	Canal LINE Official Account
TikTok	`Channel::Tiktok`	Mensagens diretas do TikTok
E-mail	`Channel::Email`	Caixa de e-mail (IMAP/SMTP ou encaminhamento)

Qual campo identifica cada canal

A resposta de inbox traz um identificador público diferente conforme o canal. Ele serve para distinguir duas inboxes do mesmo tipo — dois números de WhatsApp, duas contas de TikTok. Nenhum deles é credencial: são os mesmos dados que aparecem na tela de configuração da inbox.

Canal	Campo	Observação
WhatsApp	`phone_number`	—
Twilio (WhatsApp e SMS)	`phone_number`	exibido sem o prefixo whatsapp:; cai para messaging_service_sid quando não há número. O valor armazenado não muda.
SMS (Bandwidth)	`phone_number`	—
Web Widget	`website_url`	—
E-mail	`email`	—
Facebook	`page_id`	—
Instagram	`instagram_id`	—
Telegram	`bot_name`	exibido com @ na frente, acrescentado quando o valor armazenado não tem
TikTok	`business_id`	—
LINE	`line_channel_id`	—
API	`inbox_identifier`	não confundir com webhook_url

Identificador ausente vem vazio, nunca com credencial no lugar. Se a sua integração precisa distinguir inboxes, use este campo em vez do name, que o cliente pode renomear a qualquer momento.