Aprenda a integrar a Poli com outras ferramentas e automatizar seus processos utilizando nossa API. Aqui você encontrará os principais endpoints, exemplos de requisições e instruções de uso.
Autenticação (Token de API)
Para realizar integrações da Poli com outras plataformas, você precisará de um Token de API. Este código funciona como a chave de acesso exclusiva da sua empresa para autenticar as requisições.
Passo a passo para emitir o seu token:
- Acesse a Página Inicial do seu painel.
- No menu de navegação, clique em Configurações.
- Acesse a área de Integrações e selecione a aba API.
- Clique no botão Criar novo token.
- Defina um nome de identificação para o seu token.
- O sistema irá gerar o código de acesso. Copie o token gerado para utilizá-lo no cabeçalho das suas requisições HTTP.
Aviso de Segurança: Trate este token com o mesmo cuidado que você tem com senhas. Ele concede acesso direto aos dados da sua empresa. Nunca o exponha em repositórios públicos ou o compartilhe com pessoas não autorizadas
Autenticação e Configuração
Esta API segue os padrões REST, utilizando JSON para o corpo das requisições e respostas.
Base URL
Todas as requisições devem ser enviadas para:
https://app.poli.digital/api/v1
Token de Acesso (Bearer Token)
Para autenticar, você deve incluir o token no cabeçalho (Header) de cada requisição:
Header > Authorization
Valor > Bearer SEU_TOKEN_AQUI
Parâmetros Globais de Caminho (Path Params)
Estes identificadores aparecem frequentemente nas URLs:
{{customer}}: O ID exclusivo da sua conta/empresa na Poli.{{contact}}: O ID do contato (cliente).{{user}}: O ID do atendente/usuário interno.{{channel}}: O ID do canal de comunicação (ex: o ID da instância do WhatsApp).{{tag}}:O ID exclusivo da tag criada no sistema.
Endpoints Principais
Chats
Listar todos os chats
Retorna a lista de conversas ativas na conta.
- Método: GET
- URL:
/customers/{{customer}}/chats
Listar mensagens de um chat
Lista o histórico de mensagens de um contato específico.
- Método: GET
- URL:
/customers/{{customer}}/chats/contacts/{{contact}}/messages
Mensagens (WhatsApp)
Enviar Mensagem de Texto ou Mídia
- Método: POST
- URL:
/customers/{{customer}}/whatsapp/send_text/channels/{{channel}}/contacts/{{contact}}/users/{{user}}
Exemplo do body da Requisição (JSON):
{
"usermsg": "Sua mensagem de texto aqui",
"database64": "",
"mimetype": "",
"caption": ""
}
Detalhes dos Campos:
- usermsg (String / Obrigatório): O conteúdo da mensagem de texto que será enviada.
- database64 (String / Opcional): O arquivo convertido em Base64 para envio de mídia (fotos, PDFs). Não inclua o prefixo
data:image/...a menos que seja exigido. - mimetype (String / Opcional): O tipo do arquivo enviado (exemplos:
image/png,application/pdf). - caption (String / Opcional): Legenda que acompanhará o arquivo enviado.
Tags
Criar nova Tag
- Método: POST
- URL:
/tags/{{customer}}
Exemplo do Body da Requisição (JSON):
{
"name": "Nome da Tag",
"color": "#FF0000"
}
Listar tags
- Método: GET
- URL:
/api/v1/tags/{{customer}}
Adicionar tag a um contato
- Método: POST
- URL:
/api/v1/tags/{{customer}}/{{tag}}/addContact/{{contact}}
Deletar Tags
Método: DELETE
- URL: /api/
v1/tags/{{customer}}/{{tag}}
Parâmetros de Seleção, Ordenação e Filtro
Todas as URLs do tipo GET que pertencem a esta API contam com até 3 parâmetros possíveis de serem inseridos junto à URL: parâmetro de Seleção, de Ordenação e de Filtragem específica.
Filtrar por campos
Podemos filtrar apenas campos específicos. Isso pode ser realizado utilizando o parâmetro filters.
Ex: Buscar apenas os campos id, customer_id e category_id na busca de chats abertos por usuário. Para isso, nossa URL deve ser criada da seguinte forma:
https://app.poli.digital/api/v1/customers/{id}/chats?filters=id,customer_id,category_id
Ordenação
A ordenação de uma busca é realizada através do parâmetro sort.
Ex: Buscar todos os chats com ordem crescente de id:
https://app.poli.digital/api/v1/customers/{{customer}}/chats?sort=id
Ex2: Buscar todos os chats com ordem decrescente de id:
https://app.poli.digital/api/v1/customers/{{customer}}/chats?sort=-id
Atente-se para o sinal (-) na ordenação decrescente.
Também é possível ordenar por dois ou mais parâmetros simultaneamente. Ex3: Buscar todos os chats com ordem crescente de id e, dentro desta ordem, buscar em ordem decrescente de customer_id
https://app.poli.digital/api/v1/customers/{{customer}}/chats?sort=id,-user_id
Filtragem Específica
Esta API permite que você faça um filtro de um valor específico para um campo, retornando apenas os dados que possuem este filtro.
Ex: Buscar, entre todos os chats, apenas aqueles cujo nome do contato contenha 'teste'.
https://app.poli.digital/api/v1/customers/{{customer}}/?name=teste
É possível filtrar por dois ou mais campos simultaneamente, utilizando a seguinte sintaxe:
https://app.poli.digital/api/v1/customers/{{customer}}/?name=teste&phone=981000000
Concatenar dois ou mais parâmetros
É possível utilizar seleção e ordenação ao mesmo tempo.
Ex: Buscar apenas os campos id, customer_id e category_id de todos os chats, ordenando por id decrescente.
https://app.poli.digital/api/v1/customers/{{customer}}/chats?fields=id,customer_id,category_id&sort=-id
Também é possível utilizar filtragem específica e ordenação ao mesmo tempo.
Ex: Buscar, entre todos os chats, aqueles cujo nome do contato seja igual a 'teste', ordenados por id decrescente.
https://app.poli.digital/api/v1/customers/{{customer}}/?name=teste&orderBy=-idMias exemplos de endpoints: https://cs.poli.digital/api-cliente