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 a API do Intercom (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 o 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 Help Center de Artigos, seu conteúdo fica disponível por padrão através do intercom.help. Sua URL ficará assim: intercom.help/exampleapp.

Se você quiser usar uma URL diferente, 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 dos EUA) • Para Configuração Manual/HTTP: custom.intercom.help (região dos EUA) 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 Artigos no seu domínio personalizado:

Sim! Se você ativar “HTTPS (quick setup)” nas configurações do Help Center, o Intercom irá automaticamente provisionar e gerenciar 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 quiser 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 de SSL e HTTPS não resolveram seu problema, os seguintes cenários cobrem casos comuns para domínios personalizados do Help Center:

1. Domain 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 "Not found" na URL pública, mas os artigos aparecerem corretamente no seu workspace:

Se você encontrar comportamento inesperado em seu Help Center, comece com estes passos antes de investigar a configuração:

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 Intercom API, 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 Intercom API:

Sim, se você quiser acionar um artigo no Messenger, pode usar o showArticle método 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 de criação de contatos para criar um script que importe users ou seguir este tutorial que fornecerá os 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.

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

Então você poderá recuperar o acesso aos dados dos contatos através do endpoint da API para obter um contato e suas conversas através do endpoint da API para recuperar uma conversa.

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, você tem duas opções.

A primeira opção é atribuir uma conversa diretamente a um admin ou a uma equipe usando o endpoint da API para gerenciar uma conversa. Você precisa ter acesso ao ID provisionado pelo 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 o endpoint da API para executar regras de atribuição em uma conversa. 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, na 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 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 o endpoint da API para responder a uma conversa. Você precisará escolher um message_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, na coleçã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 o endpoint da API para adicionar tag a uma conversa, você precisará ter acesso ao conversation_id da conversa a ser marcada, 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, na coleçã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 o endpoint da API para criar uma conversa. 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 solicitação.

Você pode testar a funcionalidade no recurso "Try It" na nossa documentação para desenvolvedores, na coleçã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 o endpoint da API para gerenciar uma conversa. 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 o endpoint da API para redigir parte de uma conversa.

Você pode testar a funcionalidade no recurso "Try It" na nossa documentação para desenvolvedores, na coleçã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 tomada, como um colega de equipe sendo designado 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 aqui. Também precisará ter uma URL de endpoint publicamente acessível disponível para que a ação seja executada quando 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, quando você recupera uma conversa à qual a conversa paralela está anexada, 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 precisa criar ou obter o tipo de ticket para rotular o novo ticket. Então você 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 o endpoint da API para buscar tickets. Para excluir tipos de ticket 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 back office.

Se você estiver usando a API para recuperar uma conversa ou listar conversas com tickets back office associados às conversas e quiser excluí-los, você pode filtrar os resultados que têm o tipo de ticket 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 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 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 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 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 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.

As APIs Intercom para listagem e busca de recursos oferecem paginação baseada em cursor. Isso está disponível para que, quando você 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á a aparência de algo 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 as APIs de listagem e as 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ê estiver acessando dados apenas dentro do seu próprio workspace Intercom, pode usar um token de acesso.

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

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

Para encontrar seu token de acesso 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 sua Intercom Inbox usando o Canvas Kit, um kit de ferramentas que permite criar apps que funcionam diretamente na 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 documentos 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 na 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 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, deverá 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 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, 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 em seu app, tenha conversas com seus clientes, envie mensagens ricas de saída, 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 em seu app, tenha conversas com seus clientes, envie mensagens ricas de saída, 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.