API do Starchats

Visão geral

O Starchats expõe quatro APIs com objetivos e credenciais diferentes. A API de Aplicação atende a maior parte das integrações. Plataforma administra contas externamente, Canal API cria canais próprios e Widget sustenta o chat do site.

Relatórios também possuem rotas em /api/v2/accounts/{account_id}/reports, com a mesma autenticação da API de Aplicação.

Como obter IDs e substituir placeholders

Obter o {account_id}

O {account_id} é o identificador numérico da conta, não o ID do usuário. Você pode encontrá-lo de duas formas:

1. No painel: abra a conta e observe a URL. Em /app/accounts/123/..., o {account_id} é 123.
2. Pela API: consulte o perfil autenticado. O array accounts retorna o campo id de cada conta acessível ao token.

{
  "id": 7,
  "email": "agente@empresa.com.br",
  "accounts": [
    { "id": 123, "name": "Minha empresa", "role": "administrator" }
  ]
}

Nesse exemplo, use 123 no lugar de {account_id}.

Obter IDs dos recursos

Liste ou crie o recurso e guarde o campo id devolvido no JSON. Todos os exemplos da referência mostram quais placeholders são necessários.

Identificadores da Canal API

{inbox_identifier} não é igual a {inbox_id}. Ele identifica e autentica uma caixa do tipo API e aparece na configuração dessa caixa. Trate-o como segredo. Já {source_id} é retornado ao criar um contato pela Canal API e identifica aquele contato dentro da caixa.

Autenticação

Há três mecanismos principais. Eles não são intercambiáveis: escolha a credencial da superfície que será consumida.

A API está habilitada por padrão em todas as contas. Uma resposta 403 com “API access is not enabled for this account” só deve aparecer se essa regra for alterada na instalação.

Token de API

api_access_token é um token opaco de longa duração associado a um usuário ou Agent Bot. Não é JWT e não usa o esquema Bearer.

curl -sS 'https://SEU_DOMINIO/api/v1/accounts/{account_id}/conversations' \
  -H 'api_access_token: SEU_TOKEN'

Obter e rotacionar

O usuário encontra a credencial em Perfil › Configurações do perfil › Token de acesso. Também pode rotacioná-la pelo endpoint abaixo; o token anterior é invalidado imediatamente.

O token herda todas as permissões do usuário em todas as contas das quais ele participa. Não existe escopo nativo por conta ou recurso. Para integrações, crie um usuário dedicado com função personalizada restrita.

Sessão, login e MFA

{ "email": "agente@empresa.com.br", "password": "..." }

Sem MFA, a resposta é 200. O corpo inclui access_token, o token permanente de API; os headers trazem a sessão do dashboard:

access-token: <token de sessão>
client:       <id do dispositivo>
uid:          <e-mail>
expiry:       <timestamp>

Segunda etapa do MFA

Com MFA, a primeira resposta é 206 Partial Content e contém um JWT HS256 válido por cinco minutos:

{ "mfa_required": true, "mfa_token": "eyJhbGciOiJIUzI1NiJ9..." }

Envie no mesmo endpoint o mfa_token com otp_code ou backup_code. O JWT de MFA não autentica endpoints da API.

Cada usuário pode manter até 25 sessões. Clientes não navegador expulsam a sessão mais antiga ao alcançar o limite; o dashboard recebe 409 para escolher uma sessão a encerrar.

Tokens de Agent Bot

Bots usam o mesmo header api_access_token, porém só acessam ações autorizadas explicitamente.

Qualquer outra ação retorna 401 com “Access to this endpoint is not authorized for bots”. O token só aparece ao listar bots para um administrador.

API de Aplicação

É a superfície principal do produto. Todos os recursos vivem sob o prefixo da conta e aceitam api_access_token ou a sessão usada pelo dashboard.

O token precisa pertencer a um usuário membro da conta indicada, com permissão para a ação. Para conferir verbos, caminhos e parâmetros exatos da versão instalada:

bundle exec rails routes | grep 'api/v1/accounts'

API de Plataforma

Permite criar e administrar contas e usuários a partir de um sistema externo. Autentique com o api_access_token de um Platform App, criado somente pelo super administrador em /super_admin/platform_apps.

O app só pode acessar recursos presentes em platform_app_permissibles. Fora dessa lista, a API retorna 401 com “Non permissible resource”. Recursos criados pelo próprio app entram na lista automaticamente.

Canal API pública

A Canal API não usa header de autenticação. O inbox_identifier na URL é a credencial que permite criar contatos, conversas e mensagens naquela caixa.

HMAC de identidade

Quando hmac_mandatory está ativo, envie identifier_hash como hexadecimal de:

HMAC-SHA256(hmac_token_da_caixa, identifier)

O servidor usa comparação resistente a timing attacks. Ative essa proteção quando contatos representam usuários autenticados no seu sistema.

API do Widget

Essa API é consumida pelo widget de chat e não foi projetada como interface geral de integração. Ela combina website_token com um JWT de sessão no header X-Auth-Token.

O JWT usa HS256, contém source_id, inbox_id, exp e iat, e vale 180 dias por padrão. A duração pode mudar com WIDGET_TOKEN_EXPIRY.

Webhooks de saída

A lista de eventos é fechada. Um nome fora dela falha na validação.

Assinatura HMAC

X-Starchats-Signature = "sha256=" +
  HMAC_SHA256(segredo, timestamp + "." + corpo_cru)

Calcule sobre o corpo cru, rejeite timestamps antigos e compare em tempo constante. Não reserialize o JSON antes de validar.

Limites de requisição

Exceder um limite retorna 429. O limite global padrão é 3.000 requisições por IP a cada minuto, configurável por RACK_ATTACK_LIMIT.

Autenticação

API de Aplicação

Widget

Os dois primeiros limites do widget usam IP + website_token. O bloco pode ser desligado com ENABLE_RACK_ATTACK_WIDGET_API=false. Valores ajustáveis podem diferir na sua instalação.

Respostas e paginação

O formato é JSON. A maioria dos índices aceita page, mas o tamanho varia: conversas usam 25, contatos 15 e anexos da conversa 100. Leia os metadados retornados; a contagem pode aparecer em meta ou em headers conforme o recurso.

Exemplos completos

Listar conversas abertas

curl -sS 'https://SEU_DOMINIO/api/v1/accounts/{account_id}/conversations?status=open' \
  -H 'api_access_token: SEU_TOKEN'

Enviar uma mensagem

curl -sS -X POST \
  'https://SEU_DOMINIO/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages' \
  -H 'api_access_token: SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"content":"Olá! Como posso ajudar?","message_type":"outgoing","private":false}'

Criar contato, conversa e mensagem pelo Canal API

# 1. Criar contato; guarde o source_id retornado
curl -sS -X POST \
  'https://SEU_DOMINIO/public/api/v1/inboxes/{inbox_identifier}/contacts' \
  -H 'Content-Type: application/json' \
  -d '{"identifier":"cliente-123","name":"Maria","email":"maria@exemplo.com.br"}'

# 2. Criar conversa
curl -sS -X POST \
  'https://SEU_DOMINIO/public/api/v1/inboxes/{inbox_identifier}/contacts/{source_id}/conversations' \
  -H 'Content-Type: application/json'

# 3. Enviar mensagem
curl -sS -X POST \
  'https://SEU_DOMINIO/public/api/v1/inboxes/{inbox_identifier}/contacts/{source_id}/conversations/{conversation_id}/messages' \
  -H 'Content-Type: application/json' \
  -d '{"content":"Preciso de ajuda"}'

Segurança

• Crie um usuário dedicado e restrito para cada integração; o token de API não possui escopo próprio.
• Trate inbox_identifier como credencial e habilite HMAC de identidade para usuários autenticados.
• Valide assinatura, timestamp e identificador de entrega de todos os webhooks.
• Planeje a rotação de SECRET_KEY_BASE, pois ela encerra widgets e fluxos MFA/OAuth em andamento.
• Trocar a senha derruba sessões, mas não invalida api_access_token; use o endpoint de rotação.
• Não grave tokens, corpos sensíveis ou segredos de webhook em logs.