Use este artigo para configurar seu ambiente de desenvolvimento 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 para 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 é necessário configurar SSL manualmente — 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 cenários a seguir 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 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. Também é possível alterar a versão que seu app está usando no 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. 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 fornecerá exemplos de código para começar.

Certifique-se de configurar uma verificação de limitação de taxa para garantir que você não ultrapasse o limite, que atualmente é de 10.000 chamadas API por minuto para cada app e 25.000 chamadas 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 tratamento adequado da limitação de taxa. Certifique-se de que seu script respeite os limites de taxa (10.000 chamadas 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 tratadas 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 API se você tiver o ID do contato.

Então você poderá acessar novamente os dados dos contatos através do endpoint get a contact API e suas conversas através do endpoint retrieve a conversation API.

Não, atualmente não há como excluir notas individuais ou excluir notas em massa de 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 excluídas manualmente dentro do workspace, mas apenas uma por vez.

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

A primeira opção é atribuir uma conversa diretamente a um admin ou a uma equipe usando oendpoint manage a conversation API. Você precisa ter acesso ao ID provisionado pelo Intercom para a conversa, assim como ao admin_id e ao 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 API. Você precisa ter acesso ao ID provisionado pelo Intercom para a conversa.

Você pode testar a funcionalidade no recurso "Try It" na nossa documentação para desenvolvedores, nacoleçã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 token bearer.

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

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

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 API, você precisará ter acesso ao conversation_id da conversa para marcar, ao ID provisionado pelo Intercom da tag e ao admin_id.

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

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

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

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

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

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

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

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

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

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

Conversas paralelas não têm um endpoint dedicado, então você não pode recuperá-las diretamente. No entanto, ao recuperar uma conversa à qual a conversa paralela está anexada, você verá partes da conversa que aparecem como "part_type": "side_conversation_reply" com o conteúdo das mensagens do user na conversa paralela.

Para criar um ticket usando a API do Intercom, você primeiro precisará criar ou obter o tipo de ticket para rotular o novo ticket. Depois, pode criar o ticket usando uma requisição curl ou com a 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 ticket, pode usar oendpoint search tickets API. Para excluir tipos de ticket 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 ticket 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 resultados que tenham 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á existir 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 você não ultrapasse 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 de solicitações separado, 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 que você está usando para consultar a API. Para corrigir isso, ajuste os parâmetros da consulta da API para corresponder ao 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 UI de relatórios do Intercom. Algumas métricas disponíveis na UI 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 UI versus relatórios extraídos usando a API de conversas, pode notar uma diferença no número de conversas. Isso ocorre porque os tickets de back office associados a uma conversa serão incluídos quando extraídos da API.

Para resolver isso, você pode filtrar os resultados após recuperá-los via API de list conversations, retrieve a conversation ou search for conversations, 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 houver um webhook que sua equipe precise, por favor envie uma solicitação para a equipe ou adicione à lista de desejos do produto na comunidade Intercom.

Ao construir sobre 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 solicitaçõ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 para configurar OAuth.

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

Se você está acessando dados apenas dentro do seu próprio workspace Intercom, pode usar um access token.

Se você está construindo um app privado que acessa dados apenas no seu workspace Intercom, pode usar seu Intercom access token para autenticação. Encontre seu access token no seu developer hub e saiba mais sobre autenticação aqui.

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

Para encontrar seu API access token, 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 construir um app para sua 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 construir seu primeiro app para Inbox. Você também pode aprender mais sobre o Canvas Kit e encontrar documentos de referência em nossa documentação para desenvolvedores.

Você pode construir 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.

Note 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 construir seu primeiro app para Inbox. Você também pode aprender mais sobre o Canvas Kit e encontrar documentos 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 Install app ao lado do workspace onde deseja instalar o app. Este app será instalado e um Access Token será fornecido para esse workspace para que você possa acessar seus dados através da API.

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

Quando estiver pronto para publicar seu app, siga 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.