Documentacao da API IAra
Pesquise aqui os artigos ou procure as categorias abaixo.
Browse by topic
Find guides, tutorials, and answers organised by category.
Escopo e primeiros passos
O que o cliente pode usar na API IAra, limites de escopo, base URL, autenticacao e padroes de resposta.
Browse
Contatos e identificadores
Criar, buscar, atualizar, filtrar, mesclar contatos e vincular contatos a caixas de entrada.
Browse
Conversas e mensagens
Listar, criar, atribuir, atualizar, etiquetar, priorizar conversas e enviar mensagens pela conta.
Browse
Client API e canais proprios
Criar experiencias proprias de chat com inbox_identifier, contatos publicos, conversas publicas e mensagens.
Browse
Organizacao da conta
Recursos de conta como agentes, times, caixas, etiquetas, respostas prontas, atributos e filtros personalizados.
Browse
Automacoes e webhooks
Webhooks, regras de automacao e hooks de integracao disponiveis no escopo da conta.
Browse
Relatorios e auditoria
Metricas de conta, agentes, times, canais, eventos de conversa, CSAT e auditoria quando habilitada.
Browse
Central de ajuda via API
Gerenciar portais, categorias e artigos da central no escopo da conta.
Browse
Erros e boas praticas
Erros HTTP, paginacao, idempotencia, uso seguro de tokens e checklist de suporte para integracoes.
Browse
Popular articles
What other people are reading right now.
Mapa completo dos recursos de conta
Mapa completo dos recursos de conta A documentacao da API IAra separa os recursos entre Application API e Client API. O cliente deve usar somente rotas que atuam dentro da propria conta. Application API incluida nesta central Grupo oficial Escopo IAra Account Consultar/atualizar dados permitidos da conta Profile Consultar/atualizar perfil do usuario autenticado Agents Gerenciar agentes conforme permissao Teams Gerenciar times conforme permissao Inboxes Consultar caixas; criacao de canais pode depender da Digi2B Contacts Criar, buscar, atualizar, filtrar e mesclar contatos Contact Labels Ler e atualizar etiquetas de contato Conversations Listar, filtrar, criar, atualizar, priorizar e alterar status Conversation Assignments Atribuir conversa a agente/time Conversation Labels Ler e atualizar etiquetas de conversa Messages Listar, criar e, quando permitido, remover mensagens Canned Responses Gerenciar respostas prontas Labels Gerenciar etiquetas da conta Custom Attributes Gerenciar campos personalizados Custom Filters Gerenciar filtros salvos Automation Rules Gerenciar automacoes liberadas na conta Integrations Gerenciar hooks de integracoes liberadas Webhooks Enviar eventos para sistemas externos Reports Consumir metricas e eventos de atendimento Audit Logs Disponivel apenas quando habilitado no plano/conta Help Center Gerenciar portais, categorias e artigos da conta Fora do escopo Acoes fora da conta do cliente, provisionamentos e configuracoes gerenciadas pela Digi2B nao entram nesta central publica. Quando um recurso depender da Digi2B, o artigo deve dizer isso de forma explicita.
π§ Escopo e primeiros passosPaginacao, filtros e respostas
Paginacao, filtros e respostas Muitos endpoints retornam listas paginadas. O formato pode variar por recurso, mas geralmente a resposta vem com payload e meta. Exemplo curl -X GET "$BASE_URL/api/v1/accounts/$ACCOUNT_ID/conversations?page=2" \ -H "api_access_token: $API_TOKEN" Filtros comuns Filtros variam por endpoint. Os mais frequentes sao: - page - status - inbox_id - team_id - assignee_id - from - to - q Recomendacao para integracoes - Sempre leia a resposta antes de assumir formato fixo. - Trate pagina vazia como fim da sincronizacao. - Grave IDs externos para evitar duplicidade. - Nao use consultas grandes em tempo real se puder sincronizar em lote. - Em retries, evite repetir criacoes sem idempotencia. Exemplo de loop conceitual page = 1 while true: buscar page se payload vazio: parar processar itens page += 1
πͺͺ Contatos e identificadoresContatos: filtros, labels, merge e contact inboxes
Contatos: filtros, labels, merge e contact inboxes A API de contatos tambem cobre filtros, etiquetas, mesclagem e relacao entre contato e caixa de entrada. Filtros de contato Use /contacts/filter para consultas estruturadas quando a busca simples nao for suficiente. Exemplos: contatos por atributo, canal, data ou estado de cadastro. Etiquetas do contato curl -X POST "$BASE_URL/api/v1/accounts/$ACCOUNT_ID/contacts/123/labels" \ -H "api_access_token: $API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"labels":["cliente-premium", "api"]}' A atualizacao de labels pode substituir a lista existente. Leia a resposta e preserve etiquetas que nao devem ser removidas. Contactable inboxes Use /contacts/:id/contactable_inboxes para descobrir em quais caixas o contato pode ser acionado. curl -X GET "$BASE_URL/api/v1/accounts/$ACCOUNT_ID/contacts/123/contactable_inboxes" \ -H "api_access_token: $API_TOKEN" Contact inbox Use /contacts/:id/contact_inboxes para criar vinculo entre contato e inbox quando o fluxo exigir e o usuario tiver permissao. Merge Use merge apenas quando tiver certeza de que dois contatos representam a mesma pessoa. Depois da mesclagem, o contato secundario e removido. Cuidados Mesclagem e etiquetas afetam a operacao do atendimento. Registre quem fez a alteracao, IDs envolvidos e motivo.
π§ Escopo e primeiros passosBase URL, autenticacao e IDs
Base URL, autenticacao e IDs Os exemplos da API IAra usam a URL da plataforma Digi2B: export BASE_URL="https://app.digi2b.com" export ACCOUNT_ID="59" export API_TOKEN="seu_token_da_iara" Application API Use para automacoes autenticadas no escopo da conta: /api/v1/accounts/:account_id Autenticacao: -H "api_access_token: $API_TOKEN" Client API Use para experiencias proprias de chat em uma caixa de API ja configurada: /public/api/v1/inboxes/:inbox_identifier A Client API usa inbox_identifier, contact_identifier e, quando habilitado, identifier_hash. IDs comuns ID Onde aparece account_id URL da conta e rotas autenticadas inbox_id Caixas/canais da conta inbox_identifier Caixa de API para Client API contact_id Contato dentro da conta conversation_id Conversa interna display_id Numero visivel da conversa no painel agent_id Agente da conta team_id Time da conta Primeiro teste curl -X GET "$BASE_URL/api/v1/accounts/$ACCOUNT_ID/inboxes" \ -H "api_access_token: $API_TOKEN" Se esse teste falhar, confira token, conta, permissao do usuario e ambiente antes de seguir.
πͺͺ Contatos e identificadoresContatos: criar, listar, buscar e atualizar
Contatos: criar, listar, buscar e atualizar Contatos representam pessoas atendidas pela IAra. Use identifier para vincular o contato ao ID do seu sistema externo. Criar contato curl -X POST "$BASE_URL/api/v1/accounts/$ACCOUNT_ID/contacts" \ -H "api_access_token: $API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Maria Cliente", "email": "[email protected]", "phone_number": "+5554999999999", "identifier": "crm-12345", "custom_attributes": {"origem":"digi2b.com"} }' Listar e buscar curl -X GET "$BASE_URL/api/v1/accounts/$ACCOUNT_ID/contacts" \ -H "api_access_token: $API_TOKEN" curl -X GET "$BASE_URL/api/v1/accounts/$ACCOUNT_ID/contacts/[email protected]" \ -H "api_access_token: $API_TOKEN" Atualizar curl -X PUT "$BASE_URL/api/v1/accounts/$ACCOUNT_ID/contacts/123" \ -H "api_access_token: $API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name":"Maria Cliente", "custom_attributes":{"plano":"premium"}}' Boas praticas Busque antes de criar, normalize telefone com DDI e mantenha identifier estavel. Evite criar duplicidade quando o mesmo contato chega por canais diferentes.
π Central de ajuda via APIPortais, categorias e artigos via API
Portais, categorias e artigos via API A Help Center API permite gerenciar portais, categorias e artigos no escopo da conta quando o recurso esta habilitado. Listar portais curl -X GET "$BASE_URL/api/v1/accounts/$ACCOUNT_ID/portals" \ -H "api_access_token: $API_TOKEN" Criar categoria curl -X POST "$BASE_URL/api/v1/accounts/$ACCOUNT_ID/portals/api-reference/categories" \ -H "api_access_token: $API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name":"Primeiros passos", "slug":"primeiros-passos", "description":"Guias iniciais", "position":10, "locale":"pt" }' Criar artigo curl -X POST "$BASE_URL/api/v1/accounts/$ACCOUNT_ID/portals/api-reference/articles" \ -H "api_access_token: $API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title":"Visao geral", "slug":"visao-geral", "content":"# Visao geral\nConteudo do artigo.", "description":"Resumo do artigo", "category_id":56, "author_id":35, "status":0, "locale":"pt" }' Status de artigo Use rascunho para revisao antes de publicar. Publique apenas conteudo aprovado e testado.