initdesk
Cadastrar-se
Voltar ao blog
Suporte ao cliente

API, webhooks ou BYOD: qual integração você precisa?

Três formas de conectar o initdesk à sua stack — e apenas uma delas é a nova API, no ar hoje em developers.initdesk.com.

Se você leu o marketing do initdesk, provavelmente viu "conecte qualquer API". Isso geralmente significa Bring Your Own Data (BYOD): o initdesk chama seu endpoint para que agentes vejam plano, histórico de pedidos ou uso ao lado de um ticket.
Hoje estamos lançando algo diferente: a API do initdesk e documentação para desenvolvedores em developers.initdesk.com. Seus sistemas agora podem chamar o initdesk em https://api.initdesk.com para ler e escrever tickets, solicitantes, conversas e conteúdo da Central de Ajuda — a superfície suportada para CRMs, ferramentas internas, automação e portais personalizados.
Três caminhos de integração. Três direções de dados. Escolha por quem inicia a requisição HTTP, não por buzzword.

Três direções (mapa rápido)

IntegraçãoQuem chama quemMelhor para
API (nova hoje)Você → initdesk (api.initdesk.com)Criar ou listar tickets, sincronizar Central de Ajuda, CRMs e ferramentas internas
Webhooksinitdesk → sua URL HTTPSReações em tempo real quando mensagens, atribuições ou status mudam
BYODinitdesk → seu endpoint de clienteContexto de cliente ao vivo na barra lateral do ticket e rascunhos de IA
Nenhuma substitui as outras. Muitas equipes usam BYOD mais API: contexto ao lado da conversa, tickets criados do produto. Webhooks mais API é comum quando você precisa de um evento para disparar um job que depois busca detalhes completos do ticket.

Quando usar a API

A API é o padrão certo quando seu código precisa ler ou alterar dados do initdesk sob demanda.
Trabalhos típicos:
  • Criar tickets a partir de um fluxo "Fale com o suporte" no app, um CRM ou uma ferramenta operacional interna (você escolhe a caixa de entrada; o solicitante é um cliente em termos de API).
  • Listar ou buscar tickets para dashboards, relatórios de SLA ou resumos de escalação que você controla.
  • Ler ou postar mensagens quando está construindo um portal personalizado ou espelhando conversas em outro lugar.
  • Publicar ou atualizar artigos e coleções da Central de Ajuda a partir de um repositório, CMS ou pipeline de lançamento.
Tudo tem escopo de uma organização:
/organizations/{organization_id}/...
Use o ID numérico da organização em Settings → General (não o public_id em string usado em URLs do produto). Autentique com um token com escopo de organização em cada requisição:
X-Initdesk-Token: <your_token>
Emita tokens em Settings → API access (Proprietário da conta ou Admin). O valor bruto é mostrado uma vez — armazene como senha e revogue se vazar. Autenticação completa, limites de taxa e relacionamentos de entidades estão na documentação para desenvolvedores e no guia de entidades.
O esquema OpenAPI está em api.initdesk.com/schema.yaml. Para uma primeira chamada mínima, veja Conecte-se à API do initdesk em 15 minutos — publicado hoje junto com este post.
O que a API não é: substituto para integrações nativas do produto. Criar/vincular issues do Linear ainda roda na interface do initdesk e na camada de plugins; não há recurso Linear na API hoje. O fluxo em Issues do Linear a partir de tickets de suporte ainda se aplica — use a API para dados de tickets e mensagens, não para arquivar issues no Linear.

Quando webhooks são suficientes

Escolha webhooks quando o initdesk deve enviar um evento e seu trabalho é reagir — notificar Slack, disparar n8n, invalidar cache ou acrescentar uma linha em uma tabela de analytics.
Configure-os em Settings → API & Webhooks. Escolha os eventos que importam (por exemplo mensagem criada, atribuído, resolvido, status alterado). Seu endpoint deve retornar resposta 2xx em cerca de cinco segundos ou a entrega pode ser marcada como falha.
Webhooks carregam notificações, não uma exportação completa da sua conta. Se precisa de corpos estruturados de tickets, responsáveis ou campos da Central de Ajuda sob demanda, use a API (ou combine: webhook acorda seu worker, API fornece o payload).
Referência do produto: Webhooks na Central de Ajuda do initdesk.

Quando BYOD é a escolha certa

BYOD é para contexto de cliente no momento da resposta: status de cobrança, plano de assinatura, último pedido, feature flags — o que quer que viva na sua API administrativa.
O initdesk faz POST no seu endpoint HTTPS (com headers de autenticação opcionais que você configura) e renderiza a resposta na barra lateral do ticket usando templates Liquid. Esses mesmos dados podem informar respostas rascunhadas por IA, para que agentes não adivinhem a partir de linhas de assunto.
BYOD não cria tickets, lista sua caixa de entrada nem publica artigos de ajuda. Não substitui a API — e a API não puxa dados arbitrários dos seus sistemas para a barra lateral. Para essa divisão, veja Bring Your Own Data nas Atualizações do initdesk e o guia do plugin BYOD.

Combinações comuns (e um anti-padrão)

BYOD + API criar ticket — Um cliente abre suporte do seu app; você faz POST de um ticket com e-mail e assunto. Quando um agente abre a conversa, o BYOD já carregou contexto da conta ao lado.
Webhook + API recuperar — Um webhook "mensagem criada" dispara seu worker; o worker chama recuperar ticket e listar mensagens para a conversa completa antes de postar em um canal interno.
API da Central de Ajuda + hábitos editoriais — Você sincroniza artigos do git; agentes ainda seguem os padrões de conteúdo em Autoatendimento que realmente é usado para que busca e chat de IA permaneçam confiáveis.
Anti-padrão: reconstruir o initdesk no seu banco de dados — Fazer polling da API em uma caixa de entrada sombra duplica estado de responsável, notas internas e tratamento de spam que você já pagou no produto. Prefira webhooks ou leituras direcionadas para as visões que realmente precisa.

Para onde ir a seguir

O initdesk é um help desk com IA para equipes pequenas: caixa de entrada compartilhada, Central de Ajuda, BYOD, webhooks e — a partir de hoje — uma API para tickets, solicitantes, mensagens e conteúdo da Central de Ajuda. Veja Atualizações do produto para notas de lançamento e X @initdeskhq para anúncios.