Use este artigo para configurar seu ambiente de desenvolvedor Intercom, configurar um domínio personalizado do Help Center com SSL, autenticar seu app via tokens de acesso ou OAuth, e gerenciar contatos, conversas e tickets via Intercom API (Application Programming Interface). Também cobre webhooks, paginação, criação de apps Messenger e Inbox, e solução de problemas comuns de API e SSL. Destinado a desenvolvedores que criam integrações com Intercom.

Você pode criar um novo workspace de desenvolvedor para desenvolver apps. Workspaces de desenvolvedor são gratuitos e destinados apenas para fins de desenvolvimento. Depois de criar o novo workspace, você pode seguir este guia para criar um app e fazer sua primeira chamada API.

Você pode criar um novo app para seu workspace de produção e obter o token de acesso do app acessando https://app.intercom.com/a/apps/{your-workspace-id}/developer-hub/

Quando você ativa seu Articles Help Center, seu conteúdo fica disponível por padrão através do intercom.help. Sua URL ficará assim: intercom.help/exampleapp.

Se desejar usar uma URL diferente, você pode criar uma configurando manualmente um domínio personalizado. Isso envolve inserir o domínio personalizado nas configurações do Help Center, criar um registro CNAME personalizado e, opcionalmente, configurar SSL. Encontre as instruções completas para configuração em nossa documentação para desenvolvedores. Se seu Help Center mostrar um erro "não encontrado" após configurar um domínio personalizado, verifique seu registro CNAME para garantir que seu subdomínio aponte para o host correto do Intercom: • Para Configuração Rápida HTTPS: us.intercomhelpcenter.com (região US) • Para Configuração Manual/HTTP: custom.intercom.help (região US) Também verifique se o protocolo de segurança selecionado nas configurações do Help Center corresponde à sua configuração DNS.

SSL (ou TLS) é a forma mais usada para proteger a conexão entre seu servidor e seu navegador. Garante que a conexão entre servidor e navegador seja criptografada e segura, aparecendo como HTTPS.

Existem duas formas de configurar SSL com Articles no seu domínio personalizado:

Sim! Se você ativar “HTTPS (quick setup)” nas configurações do Help Center, o Intercom provisionará e gerenciará automaticamente um certificado SSL para seu domínio personalizado (como https://help.ourdomain.com). Não há necessidade de configuração manual de SSL — basta apontar seu CNAME para us.intercomhelpcenter.com, e cuidaremos do resto.

Se você pretende mudar seu domínio personalizado para HTTPS:

Você pode configurar SSL para seu domínio personalizado para manter informações sensíveis criptografadas. Se desejar fazer isso, certifique-se de ter configurado seu CNAME com um provedor DNS que suporte SSL, como Cloudflare.

Siga o guia em nossa documentação para desenvolvedores para configurar SSL. Note que, dependendo do provedor escolhido, os passos de configuração podem variar.

Se os passos padrão de configuração SSL e HTTPS não resolveram seu problema, os seguintes cenários cobrem casos comuns para domínios personalizados do Help Center:

1. Domínio Não Seguro

Erro ERR_SSL_VERSION_OR_CIPHER_MISMATCH

2. Configuração HTTPS travada em pendente

3. Opção HTTPS (Configuração Rápida) Não Disponível

4. Erro de Acesso Negado

Se a URL de um artigo migrado não funcionar mais após mover o conteúdo para o Intercom:

Se seu Help Center mostrar um erro "Não encontrado" na URL pública, mas os artigos aparecerem corretamente no seu workspace:

A versão atual da API é 2.15. Você pode encontrar a documentação da API em nosso site de documentação para desenvolvedores. Você também pode alterar a versão que seu app está usando no seu Developer Hub seguindo os passos listados neste guia.

Se você estiver usando a API Intercom, também pode alterar a versão dentro do cabeçalho HTTP da sua requisição.

Os seguintes endpoints estão disponíveis na versão 2.15 da API Intercom:

Sim, se você quiser abrir um artigo no Messenger, pode usar o método showArticle da API JavaScript showArticle. O artigo será aberto dentro do Messenger e clicar no botão de voltar do Messenger retornará ao contexto anterior. Se o Messenger estiver fechado quando o método for chamado, ele será aberto primeiro e então o artigo será exibido. Isso está disponível em todas as plataformas no Messenger.

No Intercom, users são classificados como contatos. Não há um endpoint para criar contatos em massa usando a API, mas você pode usar o endpoint create contacts para criar um script que importe users ou siga este tutorial que fornece exemplos de código para começar.

Certifique-se de configurar uma verificação de rate limiting para garantir que você não ultrapasse o limite, que atualmente é de 10.000 chamadas de API por minuto para cada app e 25.000 chamadas de API por minuto por workspace.

A API do Intercom não oferece um endpoint dedicado para criação em massa de contatos. Para importar contatos em escala, use o endpoint create contact em um loop com o devido controle de rate limit. Garanta que seu script respeite os limites (10.000 chamadas de API por minuto por app; 25.000 por minuto por workspace).

As seguintes operações em massa não estão disponíveis via API e devem ser feitas por meio de requisições individuais em loop ou exportação/importação manual:

Para recuperar os dados de um contato arquivado, primeiro você precisa desarquivar o contato, o que pode ser feito com o endpoint unarchive contact da API se você tiver o ID do contato.

Então você poderá acessar os dados do contato pelo endpoint get a contact da API e suas conversas pelo endpoint retrieve a conversation da API.

Não, atualmente não há como deletar notas individuais ou em massa dos contatos via API. Se essa funcionalidade for importante para suas operações, por favor visite o Product Wishlist para criar, comentar ou votar em um pedido de recurso. Notas podem ser deletadas manualmente dentro do workspace, mas apenas uma por vez.

Se você quiser atribuir uma conversa a uma equipe usando a API, tem duas opções.

A primeira opção é atribuir uma conversa diretamente a um admin ou a uma equipe usando oendpoint manage a conversation da API. Você precisa ter acesso ao id provisionado do Intercom para a conversa, assim como ao admin_id e assignee_id.

A outra opção é executar regras de atribuição que você já configurou na conversa usando oendpoint run assignment rules on a conversation da API. Você precisa ter acesso ao id provisionado do Intercom para a conversa.

Você pode testar a funcionalidade pelo recurso "Try It" na nossa documentação para desenvolvedores, pela coleção Intercom Postman, ou no seu próprio terminal ou IDE (Ambiente de Desenvolvimento Integrado). Não esqueça de usar seu token de acesso Intercom como bearer token.

Uma nota é um comentário interno visível apenas para colegas. Para adicionar uma nota a uma conversa, você pode usar oendpoint reply to a conversation da API. Você precisará escolher message_type como note e type como "admin", junto com o admin_id de quem a nota deve vir.

Você pode testar a funcionalidade pelo recurso "Try It" na nossa documentação para desenvolvedores, pela coleção Intercom Postman, ou no seu próprio terminal ou IDE. Não esqueça de usar seu token de acesso Intercom como bearer token.

Se você já criou uma tag na interface, pode usar essa tag para aplicar às conversas. Você também pode criar uma nova tag usando a API.

Para usar oendpoint add tag to a conversation da API, você precisará do conversation_id da conversa a ser marcada, do id provisionado do Intercom da tag e do admin_id.

Você pode testar a funcionalidade pelo recurso "Try It" na nossa documentação para desenvolvedores, pela coleção Intercom Postman, ou no seu próprio terminal ou IDE. Não esqueça de usar seu token de acesso Intercom como bearer token.

Você pode criar uma conversa pela API iniciada por um contato (ou seja, user ou lead) usando oendpoint create a conversation da API. A conversa pode ser apenas uma mensagem in-app.

Você também precisará do id provisionado do Intercom para o contato e do texto do corpo para usar como mensagem ao fazer a requisição.

Você pode testar a funcionalidade pelo recurso "Try It" na nossa documentação para desenvolvedores, pela coleção Intercom Postman, ou no seu próprio terminal ou IDE. Não esqueça de usar seu token de acesso Intercom como bearer token.

Para fechar uma conversa usando a API, você pode usar oendpoint manage a conversation da API. Você precisará do id provisionado do Intercom da conversa, seu admin_id e usar message_type "close".

Se precisar redigir apenas uma parte da conversa, use oendpoint redact a conversation part da API.

Você pode testar a funcionalidade pelo recurso "Try It" na nossa documentação para desenvolvedores, pela coleção Intercom Postman, ou no seu próprio terminal ou IDE. Não esqueça de usar seu token de acesso Intercom como bearer token.

Para configurar uma notificação personalizada quando uma ação for tomada, como um colega sendo atribuído a uma conversa, você pode usar webhooks.

Você deve usar o tópico conversation.admin.assigned. Você pode encontrar todos os tópicos de conversa na nossa documentação para desenvolvedores.

Você pode se inscrever nesse tópico de webhook no hub de desenvolvedores seguindo os passos deste guia aqui. Também precisará de uma URL de endpoint publicamente acessível para que a ação ocorra quando o webhook for acionado e entregue a notificação ao seu canal preferido.

Side conversations não têm endpoint dedicado, então não podem ser recuperadas diretamente. Porém, ao recuperar uma conversa à qual a side conversation está anexada, você verá partes da conversa com "part_type": "side_conversation_reply" contendo o conteúdo das mensagens do usuário na side conversation.

Para criar um ticket usando a API do Intercom, primeiro você precisa criar ou obter o tipo de ticket para rotular o novo ticket. Depois, pode criar o ticket usando uma requisição curl ou uma linguagem de programação de sua escolha.

Siga este guia da nossa documentação para desenvolvedores para criar um tipo de ticket e criar um novo ticket.

Se você estiver usando a API para recuperar tickets e dados de tickets, pode usar o endpoint de busca de tickets da API. Para excluir tipos de tickets de back office, defina o campo como ticket_type_id e use o operador != para excluir o ticket_type_id atribuído aos tipos de tickets de back office.

Se você estiver usando a API para recuperar uma conversa ou listar conversas com tickets de back office associados às conversas e quiser excluí-los, você pode filtrar os resultados que têm o tipo de ticket de back office como atributo. Tickets vinculados podem ser encontrados no parâmetro tickets na resposta ou em linked_objects.

Outra opção disponível é usar a API para marcar conversas com um ticket de back office associado a elas. Você pode então usar a tag para filtrar por categoria de ticket.

Se você está recebendo uma mensagem 403 API Plan restricted em uma resposta, isso significa que a API que você está tentando usar não está disponível no plano do seu app.

Para acessar a API, você precisará atualizar seu plano. Você pode saber mais sobre os planos Intercom nesta página. Você pode encontrar uma lista completa de códigos de erro e respostas HTTP em nossa documentação para desenvolvedores.

Se você está recebendo uma mensagem 409 conflict em uma resposta, isso significa que há dados existentes no seu workspace Intercom que entram em conflito com os dados da solicitação. Isso pode ocorrer se você tentar criar um contato e já houver um contato com esse endereço de e-mail adicionado no seu app.

Para evitar esse erro, você pode usar o endpoint de atualização ou criar um novo contato por user_id. Você pode encontrar uma lista completa de códigos de erro e respostas HTTP em nossa documentação para desenvolvedores.

Se você está recebendo uma mensagem 429, isso significa que o cliente atingiu ou excedeu um limite de taxa, ou o servidor está sobrecarregado. Cada app tem um limite padrão de 10.000 chamadas API por minuto para cada app e 25.000 chamadas API por minuto por workspace. Mais informações sobre limites de taxa estão disponíveis em nossa documentação para desenvolvedores.

Para evitar esse erro, você pode configurar uma verificação de limite de taxa para garantir que não está atingindo o limite. Você pode encontrar uma lista completa de códigos de erro e respostas HTTP em nossa documentação para desenvolvedores.

Apps privados têm um limite padrão de 10.000 chamadas API por minuto por app e 25.000 chamadas API por minuto por workspace. Isso significa que, se um workspace tiver vários apps privados instalados, cada um contribui para o número total de solicitações.

Apps públicos têm um limite padrão de 10.000 chamadas API por minuto para cada app e 25.000 chamadas API por minuto por workspace. Isso significa que, se um workspace tiver vários apps públicos instalados, cada um tem seu próprio limite separado de solicitações, sem contribuir para os outros. Mais informações sobre limites de taxa estão disponíveis em nossa documentação para desenvolvedores.

Se você está criando seus próprios relatórios usando a API, pode notar algumas diferenças entre os dois relatórios. Isso pode acontecer por alguns motivos.

Um problema comum é quando datas e horários não coincidem. Isso geralmente ocorre porque o fuso horário que você está usando no seu workspace Intercom é diferente do fuso horário usado para consultar a API. Para corrigir isso, ajuste os parâmetros da consulta da API para coincidir com o fuso horário do seu workspace ou altere o fuso horário do seu relatório personalizado.

Outro problema é que você pode estar usando métricas que não correspondem às métricas da interface de relatórios do Intercom. Algumas métricas disponíveis na interface de relatórios não estão disponíveis via API porque são métricas calculadas. Algumas delas podem ser criadas usando a API e realizando os cálculos do seu lado. Confira o guia para criar seus próprios relatórios na documentação para desenvolvedores do Intercom.

Se você está olhando os relatórios de conversas disponíveis na interface versus relatórios puxados usando a API de conversas, pode notar uma diferença no número de conversas. Isso ocorre porque tickets de back office associados a uma conversa serão incluídos quando puxados pela API.

Para resolver isso, você pode filtrar os resultados após recuperá-los via list conversations, retrieve a conversation ou search for conversations API, e separar os tickets das conversas usando o campo ticket na resposta da API de conversa. O campo ticket será preenchido com um objeto se for um ticket e será nulo se for uma conversa.

Webhooks permitem que você se inscreva para notificações em tempo real de eventos que acontecem no Intercom, como quando um contato é criado ou uma mensagem recebida.

Você pode ver os webhooks disponíveis para cada versão em nossa documentação para desenvolvedores. Depois de identificar qual webhook você precisa, siga este guia para configurá-los.

Não há planos para adicionar novos webhooks em nosso roadmap, mas se sua equipe precisar de um webhook, por favor envie uma solicitação para a equipe ou adicione-a à lista de desejos do produto na comunidade Intercom.

Ao construir com webhooks do Intercom, tenha em mente o seguinte:

As APIs do Intercom para listagem e busca de recursos oferecem paginação baseada em cursor. Isso está disponível para que, ao solicitar uma grande quantidade de dados — como muitas conversas com todas as suas partes — você possa recebê-los e processá-los em pedaços menores.

Para exemplos de como usar paginação com as APIs de listagem do Intercom, que aceitam parâmetros de caminho, e APIs de busca, que usam parâmetros de consulta, veja nosso guia de paginação.

Para paginação baseada em cursor, o Intercom usa um ponteiro que se refere a um registro específico com base no limite que você define pelo número de páginas que especifica por solicitação.

Quando retornado em um objeto, o ponteiro terá uma aparência como 'WzXXXXXXXXXXXXXX'.

Você pode então usar o ponteiro da resposta para fazer a solicitação subsequente para o próximo lote de dados.

A formatação da paginação na solicitação difere ligeiramente entre APIs de listagem e APIs de busca, mas as respostas funcionam da mesma forma.

Você pode ver exemplos de requisições curl em nossa página de Paginação, e tutoriais sobre o uso de APIs de listagem e APIs de busca.

Qualquer app que interaja com dados de workspace de terceiros e apps construídos com Canvas Kit requerem OAuth. Você nunca deve pedir aos users seu token de acesso e deve usar apenas OAuth para interagir com seus dados.

Veja a documentação para instruções sobre como configurar o OAuth.

Você precisará configurar o OAuth se estiver criando uma integração com Intercom que acesse dados de outras pessoas no Intercom. Isso inclui apps públicos que você planeja listar na loja de apps do Intercom, bem como apps e integrações que você solicitará aos users para instalar através do seu próprio site. Saiba mais sobre OAuth na nossa documentação para desenvolvedores.

Se você estiver acessando dados apenas dentro do seu próprio workspace do Intercom, pode usar um token de acesso.

Se você estiver criando um app privado que acessa apenas dados no seu workspace do Intercom, pode usar seu token de acesso do Intercom para autenticação. Encontre seu token de acesso no seu developer hub e saiba mais sobre autenticação aqui.

Você pode usar seu token de acesso do Intercom se estiver usando a API para acessar dados no seu próprio workspace do Intercom. Encontre seu token de acesso no seu developer hub e saiba mais sobre autenticação aqui.

Para encontrar seu token de acesso da API, siga estes passos:

Sim, o Intercom Support pode rotacionar o OAuth Client Secret do seu app mediante solicitação. Uma vez rotacionado, o segredo antigo é invalidado imediatamente e o novo segredo fica disponível no Developer Hub.

Para solicitar uma rotação, entre em contato com o Intercom Support com os detalhes do seu app. Certifique-se de que sua equipe esteja preparada para atualizar a configuração da sua integração com o novo segredo imediatamente, pois o segredo antigo não será válido no momento da rotação.

Você pode criar um app para seu Intercom Inbox usando o Canvas Kit, um kit de ferramentas que permite criar apps que funcionam diretamente dentro da interface do Intercom.

Siga este tutorial para aprender a criar seu primeiro app para Inbox. Você também pode aprender mais sobre o Canvas Kit e encontrar documentação de referência em nossa documentação para desenvolvedores.

Você pode criar um app para seu Intercom Messenger usando o Canvas Kit, um kit de ferramentas que permite criar apps que funcionam diretamente dentro da interface do Intercom.

Observe que as personalizações são limitadas ao que é possível através do Canvas Kit e devem ser criadas dentro do Messenger: não é possível recriar ou modificar a aparência do Messenger.

Siga este tutorial para aprender a criar seu primeiro app para Inbox. Você também pode aprender mais sobre o Canvas Kit e encontrar documentação de referência em nossa documentação para desenvolvedores.

Se você visitar a página Test & Publish > Seus Workspaces do seu app no Developer Hub, verá todos os workspaces dos quais você (como membro da equipe Intercom) faz parte.

Você pode clicar em Instalar app ao lado do workspace onde deseja instalar o app. Este app será instalado e um Token de Acesso será fornecido para esse workspace para que você possa acessar seus dados através da API.

Para instruções de instalação de terceiros, consulte nossa documentação para desenvolvedores.

Quando estiver pronto para publicar seu app, você pode seguir os passos no developer hub. Você pode encontrar um guia sobre como publicar seu app em nossa documentação para desenvolvedores.

O Intercom SDK (Software Development Kit) para iOS permite que você use o Intercom Messenger no seu app, tenha conversas com seus clientes, envie mensagens ricas, mostre seu Help Center e acompanhe eventos.

Você pode instalar o Intercom para iOS usando Cocoapods, Swift Package Manager ou manualmente. Leia o guia completo de instalação para iOS. Você pode encontrar o Intercom para iOS no GitHub junto com um app de exemplo para explorar o SDK.

O Intercom SDK para Android permite que você use o Intercom Messenger no seu app, tenha conversas com seus clientes, envie mensagens ricas, mostre seu Help Center e acompanhe eventos.

Você pode instalar o Intercom para Android usando Gradle ou manualmente. Leia o guia completo de instalação para Android. Você pode encontrar o Intercom para Android no GitHub junto com um app de exemplo para explorar o SDK.

O wrapper Intercom React Native permite que você use o Intercom para iOS e o Intercom para Android em seus apps React Native. Siga o guia de instalação para React Native para começar.