API Contatos do Intelbras Conversas

A API de Contatos do Intelbras Conversas permite gerenciar dados de clientes.

Base URL: https://chatapi.intelbrasconversas.com.br
Autenticação: O cabeçalho Authorization: Bearer {{token}} é obrigatório em todas as requisições.


Para criar uma chave de autenticação, é necessário acessar o ambiente do https://chat.intelbrasconversas.com.br/ como um Administrador, ir em Menu - Configurações - API/Webhook e adicionar a API de acesso, como o exemplo abaixo:

Para o gerar o token de acesso, basta colocar o nome para identificação dentro do seu sistema, o canal associado e a ação associada, caso deseje usar o envio de mensagens no canal pela API:

Abaixo um exemplo de como fica o token e id do canal para utilizar nas API´s do produto:

1. Listar Contatos (GET)

Lista todos os contatos paginados.

Exemplo:

curl --location 'https://chatapi.intelbrasconversas.com.br/v1/contacts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}'

2. Criar Novo Contato (POST)

Cria um novo registro de contato.

Exemplo:

curl --location --request POST 'https://chatapi.intelbrasconversas.com.br/v1/contacts' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Megane",
    "email": "Destinee.Collins@yahoo.com",
    "number": "55489123456789",
    "isGroup": false,
    "leadStatusId": null,
    "customFields": {},
    "tags": []
}'

3. Procurar Contato por ID (GET)

Busca um contato específico utilizando o ID numérico.

Exemplo:

curl --location 'https://chatapi.intelbrasconversas.com.br/v1/contacts/14' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}'

4. Procurar Contato por Número do WhatsApp (GET)

Busca um contato específico utilizando o número completo do WhatsApp (incluindo código do país e DDD).

Exemplo (Assumindo que não há corpo na requisição GET):

curl --location 'https://chatapi.intelbrasconversas.com.br/v1/contacts/number/55489123456789' \
--header 'Authorization: Bearer {{token}}'

5. Alterar Campo Personalizável (PATCH)

Atualiza campos personalizados de um contato existente. Use o ID do contato.

Exemplo (Formato JSON simplificado para customFields):

curl --location --request PATCH 'https://chatapi.intelbrasconversas.com.br/v1/contacts/99368' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
    "customFields": {
        "CNPJ": "00.000.000/0001-00",
        "Nome da Rua": "Reese Junction"
    }
}'

6. Alterar Tag (PATCH)

Atualiza ou substitui a lista de tags de um contato existente.

Exemplo:

curl --location --request PATCH 'https://chatapi.intelbrasconversas.com.br/v1/contacts/99368' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
    "tags": ["Aniversariantes Abril", "

curl --location 'https://chatapi.intelbrasconversas.com.br/v1/api/external/{{ID_CANAL_WHATSAPP}}' \
--header 'accept: application/json' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "body": "Olá. Isso é um teste da Intelbras. Pode desconsiderar. Obrigado.",
  "number": "5548912345678",
  "externalKey": "123456",
  "mediaUrl": "https://intelbras.com/imagem.png",
  "note": {
    "body": "Nome: Intelbras Conversas\nE-mail: email_teste@intelbras.com.br\nSegmento: Telecomunicações\nCargo: Eng.\nSolicitacao: Preciso de sistema em nuvem para administrar os canais do WhatsApp dos vendedores\nProduto: Intelbras Conversas"
  }
}'

Listar Usuários (GET)

Este endpoint retorna os dados de um usuário específico do sistema (geralmente um atendente) utilizando seu ID.

Parâmetros

Exemplo de Uso

Para consultar os dados de um usuário com o ID 183:

curl --location 'https://chatapi.intelbrasconversas.com.br/v1/api/external/users/183' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}'

Resposta Esperada (200 OK)

A resposta será um objeto JSON contendo os detalhes do usuário solicitado.

API TAGS

Listar Tags (GET)

Retorna a lista de todas as tags disponíveis na sua conta.

Parâmetros

O único parâmetro é o apiId (ID da API) na URL.

Exemplo de Uso

Para listar todas as tags da API de ID 50:

curl --location 'https://chatapi.intelbrasconversas.com.br/v1/api/external/50/tags' \
--header 'Authorization: Bearer {{token}}'

Estrutura da Resposta (200 OK)

Retorna um array de objetos, onde cada objeto representa uma tag.

[
  {
    "tag": "Nome da Tag",
    "color": "#FF0000",
    "userId": 0
  }
]

Criar Múltiplas Tags (POST)

Cria múltiplas tags em um único request. Se houver erro de validação em qualquer tag, nenhuma tag será criada (operação atômica).

Parâmetros

O único parâmetro é o apiId (ID da API) na URL.

Corpo da Requisição (Body)

Deve ser um array de objetos no formato abaixo:

Exemplo de Uso

Criação de três novas tags:

curl --location --request POST 'https://chatapi.intelbrasconversas.com.br/v1/api/external/50/tags' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '[
  {
    "tag": "Tag de Suporte",
    "color": "#FF0000",
    "userId": null
  },
  {
    "tag": "Tag de Vendas",
    "color": "#00FF00",
    "userId": null
  }
]'

Remover Tag (DELETE)

Remove uma tag específica utilizando seu ID.

Parâmetros

Os parâmetros são fornecidos na URL:

Exemplo de Uso

Para remover a tag com o ID 99:

curl --location --request DELETE 'https://chatapi.intelbrasconversas.com.br/v1/api/external/50/tags/99' \
--header 'Authorization: Bearer {{token}}'

Resposta Esperada (200 OK)

{
  "message": "Tag removida com sucesso."
}

API Oportunidades

Listar Oportunidades (GET)

Este endpoint permite listar e filtrar oportunidades de negócio registradas no sistema.

Parâmetros

Os parâmetros de filtro são enviados via Query String (após o ? na URL), exceto o apiId que é parte do Path.

Exemplo de Uso

a) Listar todas as oportunidades abertas na primeira página:

curl --location 'https://chatapi.intelbrasconversas.com.br/v1/api/external/50/opportunities?pageNumber=1&status=open' \
--header 'Authorization: Bearer {{token}}'

b) Buscar oportunidades de um contato específico e em um período de tempo:

curl --location 'https://chatapi.intelbrasconversas.com.br/v1/api/external/50/opportunities?contactId=12345&startDate=2024-06-01&endDate=2024-06-30' \
--header 'Authorization: Bearer {{token}}'

Estrutura da Resposta (200 OK)

{
  "success": true,
  "data": [
    {
      "id": 101,
      "name": "Nova Venda de Sistema X",
      "status": "open",
      "contactId": 12345,
      "responsibleId": 183,
      "pipelineStepId": 3
      /* ... Outros campos da oportunidade ... */
    }
  ],
  "count": 1,
  "hasMore": false,
  "message": "Sucesso"
}

Criar Oportunidade (POST)

Este endpoint é usado para criar uma nova oportunidade de negócio, associando-a a um contato e a um estágio de pipeline (funil de vendas).

Parâmetros

O único parâmetro de Path é o apiId (ID da API) na URL.

Corpo da Requisição (Body)

O corpo da requisição deve ser um objeto JSON.

Exemplo de Uso

Criação de uma oportunidade com dois itens de produto, atribuída ao contactId: 123 e na pipelineStepId: 1:

curl --location --request POST 'https://chatapi.intelbrasconversas.com.br/v1/api/external/50/opportunities' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Venda de produto X (Nova Lead)",
    "description": "Oportunidade de venda inicial para cliente 123.",
    "value": 3000,
    "expectedCloseDate": "2025-12-31T23:59:59.000Z",
    "contactId": 123,
    "responsibleId": "456",
    "pipelineStepId": 1,
    "productsOpportunity": [
        {
            "productId": 789,
            "amount": 2,
            "value": 1500
        }
    ]
}'

Resposta Esperada (201 Created)

{
  "success": true,
  "data": {
    "id": 54321,
    "name": "Venda de produto X (Nova Lead)",
    /* ... outros dados da oportunidade criada ... */
  },
  "message": "Oportunidade criada com sucesso."
}

Buscar Oportunidade por ID (GET) 

Este endpoint permite buscar os detalhes de uma oportunidade de negócio específica utilizando seu ID.

Parâmetros

Ambos os parâmetros são fornecidos diretamente no Path (URL).

Exemplo de Uso

Para buscar os detalhes da oportunidade com o ID 54321 na integração de ID 50:

curl --location 'https://chatapi.intelbrasconversas.com.br/v1/api/external/50/opportunities/54321' \
--header 'Authorization: Bearer {{token}}'

Respostas Esperadas

Estrutura da Resposta (200 OK)

{
  "success": true,
  "data": {
    "id": 54321,
    "name": "Nome da Oportunidade",
    "value": 3000,
    "status": "open",
    "contactId": 123
    /* ... demais campos da oportunidade ... */
  },
  "message": "Sucesso"
}

Atualizar Oportunidade (PUT)

Este endpoint é utilizado para atualizar completamente os dados de uma oportunidade de negócio existente, especificada pelo seu ID.

Parâmetros

Ambos os parâmetros de identificação da oportunidade são fornecidos diretamente no Path (URL).

Corpo da Requisição (Body)

O corpo da requisição deve ser um objeto JSON contendo os campos que serão atualizados. O método PUT geralmente exige que todos os campos necessários sejam enviados, mesmo aqueles que não foram alterados, mas neste caso, é comum que a API aceite apenas os campos que se deseja modificar.

Exemplo de Uso

Atualizando o nome, valor, responsável e movendo a oportunidade 54321 para a etapa 2 do pipeline:

curl --location --request PUT 'https://chatapi.intelbrasconversas.com.br/v1/api/external/50/opportunities/54321' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Venda de produto X - Atualizada",
    "description": "Descrição atualizada da oportunidade",
    "value": 2000,
    "expectedCloseDate": "2025-12-31T23:59:59.000Z",
    "responsibleId": "789",
    "pipelineStepId": 2,
    "userId": "456"
}'

Respostas Esperadas

Estrutura da Resposta (200 OK)

{
  "success": true,
  "data": {
    "id": 54321,
    "name": "Venda de produto X - Atualizada",
    "pipelineStepId": 2
    /* ... demais dados da oportunidade atualizada ... */
  },
  "message": "Oportunidade atualizada com sucesso."
}

Atualizar Status da Oportunidade (PUT)

Este endpoint é usado para alterar o status de uma oportunidade para open (Aberta), won (Ganha) ou lost (Perdida).

Parâmetros

Ambos os parâmetros de identificação da oportunidade são fornecidos diretamente no Path (URL).

Corpo da Requisição (Body)

O corpo da requisição deve ser um objeto JSON. O campo pipelineStepId é opcional, mas recomendado para garantir que a oportunidade seja movida para a etapa final correta (won ou lost).

Exemplo de Uso

a) Marcar Oportunidade como Ganha e movê-la para a etapa final (pipelineStepId: 5):

curl --location --request PUT 'https://chatapi.intelbrasconversas.com.br/v1/api/external/50/opportunities/54321/status' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
    "status": "won",
    "pipelineStepId": 5
}'

b) Marcar Oportunidade como Perdida (pode exigir closingReasonId):

curl --location --request PUT 'https://chatapi.intelbrasconversas.com.br/v1/api/external/50/opportunities/54321/status' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
    "status": "lost",
    "closingReasonId": 10
}'

Respostas Esperadas

Estrutura da Resposta (200 OK)

{
  "success": true,
  "data": {
    "id": 54321,
    "status": "won",
    "pipelineStepId": 5
    /* ... demais dados da oportunidade atualizada ... */
  },
  "message": "Status atualizado com sucesso."
}

API Produtos

Listar Produtos Ativos (GET)

Este endpoint permite listar todos os produtos que estão atualmente ativos na conta (tenant).

Parâmetros

O único parâmetro de identificação da sua integração é fornecido no Path (URL).

Exemplo de Uso

Para listar todos os produtos ativos da integração de ID 50:

curl --location 'https://chatapi.intelbrasconversas.com.br/v1/api/external/50/products' \
--header 'Authorization: Bearer {{token}}'

Respostas Esperadas

Estrutura da Resposta (200 OK)

{
  "success": true,
  "data": [
    {
      "id": 101,
      "name": "Software X Pro",
      "description": "Licença Pro do software de gestão",
      "value": 500.00,
      "duration": 12,
      "isActive": true,
      "tenantId": 1,
      "userId": 183,
      "createdAt": "2025-10-29T20:09:56.176Z",
      "updatedAt": "2025-10-29T20:09:56.176Z"
    }
  ],
  "message": "Produtos ativos listados com sucesso"
}

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Nova Oportunidade",
      "color": "#FF0000",
      "order": 1,
      "tenantId": 1,
      "createdAt": "2025-10-29T20:12:19.973Z",
      "updatedAt": "2025-10-29T20:12:19.973Z"
    },
    {
      "id": 2,
      "name": "Qualificação",
      "color": "#00FF00",
      "order": 2,
      "tenantId": 1,
      "createdAt": "2025-10-29T20:12:19.973Z",
      "updatedAt": "2025-10-29T20:12:19.973Z"
    }
  ],
  "message": "Pipeline steps listados com sucesso"
}

Fonte base da documentação no produto: https://chat.intelbrasconversas.com.br/#/docs