Sobre esta documentação. A referência é gerada a partir do contrato publicado pela API em produção, então mostra sempre as rotas que estão no ar. Os guias explicam o que o contrato não diz: credenciais, limites, erros e eventos. A Trina responde com trechos desta documentação e indica de onde tirou cada resposta.
A API pública do Trendmulti conecta seus sistemas à plataforma. Com ela você consulta e cadastra contatos, acompanha atendimentos, envia mensagens pelos canais e mantém o CRM em dia, sem passar pela tela.
Endereçohttps://apis.trendmulti.com.brLeitura de 4 min
O que dá para fazer
Contatos e etiquetas
Listar, consultar, cadastrar e atualizar contatos; listar e cadastrar etiquetas.
Atendimentos
Listar os atendimentos do canal, também por situação, e consultar um atendimento.
Mensagens
Enviar texto, mídia, botões e templates do WhatsApp oficial; listar as mensagens de um atendimento, contato ou telefone; consultar o status de uma mensagem enviada.
Equipe
Listar usuários e departamentos.
CRM
Funis, etapas, oportunidades, clientes, produtos e motivos de perda: listar, cadastrar, atualizar e mover oportunidades entre etapas.
Chat interno
Publicar avisos dos seus sistemas nos canais públicos do chat interno da empresa, como um agente de integração.
Eventos
Receber no seu sistema os eventos de atendimento e de disparo, pelos webhooks de saída.
Endereço e formato
Endereço
Todas as chamadas vão para https://apis.trendmulti.com.br, por HTTPS.
Corpo
JSON nas duas direções. Envie o cabeçalho Content-Type: application/json nas chamadas com corpo.
Autorização
Um token de acesso no cabeçalho Authorization: Bearer, em todas as rotas menos a que gera o token (Autenticação).
Datas
ISO-8601 em UTC, como 2026-11-20T13:45:00.000Z.
Identificadores
24 caracteres hexadecimais, como 6563f0c2a1b2c3d4e5f60718.
Mensagens de erro
Sempre em português, com uma chave estável para o seu código (Erros).
A API trabalha por canal
As credenciais pertencem a um canal: um número de WhatsApp, uma conta do Instagram, um canal RCS. O token gerado com elas carrega a empresa e o canal, e cada rota usa um dos dois.
Rotas
Alcance
Listas de atendimentos e de departamentos
O canal do token.
Lista de mensagens
O canal do token; com idAttendance, o atendimento informado.
Envio de mensagens
A mensagem sai pelo canal do token.
Contatos, etiquetas, usuários e CRM
Toda a empresa.
Chat interno
Toda a empresa. A chave do agente diz quem publica.
Consultas por identificador
Toda a empresa.
Antes de começar
Módulo de API no plano. Sem ele, a aba API não aparece no canal.
Um canal conectado. A autenticação de um canal desconectado é recusada.
Acesso de administrador no Trendmulti, para pegar as credenciais na aba API do canal.
Este roteiro leva poucos minutos. Você pega as credenciais do canal, gera um token de acesso, confere que ele funciona e envia uma mensagem para um contato.
RotasPOST /api/auth›GET /api/info›POST /message/sendMessageLeitura de 5 min
1 · Pegue as credenciais do canal
No Trendmulti, abra Canais›abra o canal›API.
Se o canal ainda não tem credenciais, clique em Gerar novas credenciais.
Copie o UUID e o Token pelos botões de copiar.
2 · Gere o token de acesso
Envie o UUID e o Token para POST /api/auth. A resposta traz o token de acesso no campo token, válido por 24 horas.
Guarde o token e envie-o em todas as chamadas seguintes, no cabeçalho Authorization: Bearer <token>. Não autentique a cada chamada: o mesmo token vale por 24 horas.
3 · Confira o canal
GET /api/info devolve a empresa e o canal do token. É a forma mais simples de testar o cabeçalho de autorização.
Se a resposta for 401 com o texto Unauthorized, o token está ausente, malformado ou vencido (Usar o token).
4 · Envie uma mensagem
O envio precisa do identificador do contato. Busque um contato existente com GET /contact/pager ou cadastre um com POST /contact/create. O id da resposta é o idContact do envio.
Próximos passos
Receba eventos no seu sistema em vez de consultar a API o tempo todo.
A API usa um token de acesso (JWT) gerado a partir das credenciais do canal. O token vale por 24 horas e vai no cabeçalho de todas as chamadas.
RotaPOST /api/authLeitura de 5 min
Credenciais do canal
Cada canal tem um par de credenciais, UUID e Token, na aba API do canal (manual do usuário). Um par serve a um canal só.
Gerar novas credenciais substitui o par atual na hora: a autenticação com o par antigo passa a ser recusada. Tokens de acesso emitidos antes continuam válidos até vencer.
Gerar o token
Envie uuid e token para POST /api/auth. Esta é a única rota que não pede o cabeçalho de autorização.
successboolean
Sempre true numa resposta de sucesso.
channelobjeto
A empresa (company) e o canal (channel) do token, e expiresIn: a validade em segundos (86400, 24 horas). São os mesmos dados que GET /api/info devolve.
tokenstring
O token de acesso, para o cabeçalho Authorization.
Não existe rota de renovação. Gere um token novo antes que o atual vença, ou quando receber 401.
Sem o cabeçalho, ou com um token malformado ou vencido, a resposta é 401 com o texto Unauthorized no corpo, sem JSON. Gere um token novo e repita a chamada uma vez.
Rotas do chat interno
As rotas do chat interno (/chat/…) pedem, além do token, a chave de um agente de integração no cabeçalho X-Agent-Key:
Um administrador da empresa cadastra o agente no chat interno e copia a chave lá. Nessas rotas, o token vale pela empresa: gere-o com as credenciais de qualquer canal de atendimento conectado dela. Os detalhes estão em Agentes de integração no chat.
Erros de autenticação
Situação
Resposta
UUID ou Token errados, ou fora do formato (texto de 1 a 256 caracteres)
Empresa em período de teste que atingiu o limite de chamadas
400, com a mensagem genérica de erro.
Token ausente, malformado ou vencido nas demais rotas
401 · texto Unauthorized.
Nas rotas do chat interno, chave do agente ausente, desconhecida, de um agente removido ou de outra empresa
401 · errors.chatAgent.keyInvalid · “Chave do agente de integração ausente ou inválida. Envie a chave no cabeçalho X-Agent-Key.”
Nas rotas do chat interno, agente desativado
403 · errors.chatAgent.agentInactive · “O agente de integração está desativado.”
Nas rotas do chat interno, empresa sem o chat interno ativo
403 · errors.chatAgent.chatUnavailable · “O chat interno não está disponível para esta empresa.”
Boas práticas
Guarde UUID, Token e o token de acesso no servidor. Nunca os coloque em código de navegador, app ou repositório.
Reaproveite o token durante as 24 horas. Autentique de novo só perto do vencimento ou depois de um 401.
Se as credenciais vazarem, gere novas na aba API do canal e atualize as integrações que usam o par antigo.
Trate a chave de um agente do chat interno do mesmo jeito. Se ela vazar, peça a um administrador para gerar uma nova: a anterior para de funcionar na hora.
As rotas de lista devolvem um array simples, sem total de registros. Algumas paginam e outras devolvem tudo de uma vez.
Parâmetrospage·perPageLeitura de 4 min
Três tipos de lista
Rotas
Parâmetros
Observação
GET /contact/pager, GET /attendance/pager, GET /attendance/pager/status
page, a partir de 1, e perPage. Os dois são obrigatórios.
A API não limita perPage nessas rotas. Recomendamos até 100 por página.
GET /message/pager
page (padrão 1) e perPage (padrão 20, máximo 100).
Acima de 100, a chamada é recusada. Cada consulta tem até 5 segundos; passou disso, a resposta é 504.
Rotas /list: etiquetas, usuários, departamentos e CRM
Nenhum.
Devolvem todos os registros de uma vez.
Saber quando acabou
A resposta não traz o total. A última página é a que volta com menos itens que perPage, ou vazia. Avance page até isso acontecer.
JavaScript
async function listarContatos(token) {
const perPage = 100;
const todos = [];
for (let page = 1; ; page++) {
const res = await fetch(`https://apis.trendmulti.com.br/contact/pager?page=${page}&perPage=${perPage}`, {
headers: { Authorization: `Bearer ${token}` },
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const pagina = await res.json();
todos.push(...pagina);
if (pagina.length < perPage) break; // última página
}
return todos;
}
Ordem e alcance
Rota
Ordem
Alcance
GET /contact/pager
Cadastrados mais recentemente primeiro.
Toda a empresa.
GET /attendance/pager e /attendance/pager/status
Atualizados mais recentemente primeiro.
O canal do token.
GET /message/pager
Mais novas primeiro.
O canal do token, ou o atendimento de idAttendance.
Na lista de mensagens, informe ao menos um filtro: idAttendance, idContact ou phone (referência).
Busca de contatos
O parâmetro search de GET /contact/pager divide o texto em palavras e ignora as que têm menos de 3 letras. Cada palavra precisa aparecer no começo do nome, do e-mail, da cidade, do endereço, da empresa ou do cargo do contato, ou em qualquer parte do telefone.
Quando uma chamada falha, a API responde com um código HTTP e, na maioria dos casos, um JSON com a mensagem e a chave do erro.
Idioma das mensagenspt-BRLeitura de 6 min
Formato da resposta
JSON
{
"statusCode": 400,
"timestamp": "2026-11-20T13:45:00.000Z",
"path": "/message/pager?idAttendance=6563f0c2a1b2c3d4e5f60718&perPage=500",
"message": "O parâmetro perPage deve ser um número inteiro entre 1 e 100.",
"key": "errors.apis.invalidPerPage"
}
statusCode
O mesmo código HTTP da resposta.
timestamp
Quando o erro aconteceu, em UTC.
path
A rota chamada, com os parâmetros.
message
O texto do erro, em português.
key
A chave estável do erro, quando ele tem uma. Use a chave no seu código, não o texto.
Códigos HTTP
Código
Quando acontece
200
Sucesso. Uma consulta por identificador que não encontra o registro, ou que aponta para outra empresa, também responde 200, com o corpo vazio. No chat interno, também responde a criação de um canal que já existia e a repetição de um clientId.
201
Registro criado: rotas create, envio de mensagens, e canal ou mensagem criados no chat interno.
400
Dados inválidos ou regra de negócio recusada.
401
Credenciais inválidas, ou token ausente, malformado ou vencido. Nas rotas do chat interno, também a chave do agente ausente ou inválida.
403
Empresa bloqueada. Nas rotas do chat interno, agente desativado ou chat interno indisponível para a empresa.
404
Registro não encontrado numa atualização, ou contato de outra empresa num envio de mensagem. Nas rotas de etiquetas e de sussurro do atendimento, um atendimento ou uma etiqueta que não existem na empresa. No chat interno, um canal indisponível para o agente ou uma mensagem que não é dele.
409
Conflito. No CRM, o contato já pertence a outro cliente ou o CPF/CNPJ já está em uso. No RCS, o envio foi recusado porque o canal é só de campanha ou a sessão expirou. No atendimento, mudar etiquetas ou criar sussurro num atendimento encerrado, ou repetir um sussurro com o mesmo clientId em até 60 segundos. No chat interno, um nome de canal em uso por um canal privado ou arquivado.
413
Arquivo acima de 10 MB numa mensagem do chat interno.
429
O agente de integração passou de 60 publicações no minuto, no chat interno. Espere os segundos do cabeçalho Retry-After.
500
Erro inesperado. Tente de novo; se persistir, fale com o suporte.
503
No chat interno: o chat não respondeu a tempo ou ainda processa um pedido igual, ou o envio de arquivos está indisponível. Repita depois dos segundos do cabeçalho Retry-After, quando ele vier.
504
A consulta passou do tempo, na lista de mensagens. Refine os filtros.
Chaves de erro
Chave
Mensagem
errors.apis.attendanceClosed
O atendimento está encerrado e não aceita alterações.
errors.apis.customFieldInvalidValue
Valor inválido para o campo nome (tipo).
errors.apis.customFieldNotFound
O campo personalizado id não existe nos campos de contato da empresa.
errors.apis.customFieldsInvalid
customFields deve ser uma lista de objetos com id e value.
errors.apis.invalidCredentials
Credenciais inválidas.
errors.apis.invalidId
O parâmetro informado deve ser um identificador válido (24 caracteres hexadecimais).
errors.apis.invalidPage
O parâmetro page deve ser um número inteiro maior ou igual a 1.
errors.apis.invalidPerPage
O parâmetro perPage deve ser um número inteiro entre 1 e 100.
errors.apis.invalidPhone
O parâmetro phone deve ser um telefone em formato internacional, com DDI e DDD (ex.: 5511999998888).
errors.apis.invalidStatus
O parâmetro status aceita os valores permitidos, separados por vírgula.
errors.apis.messageFilterRequired
Informe ao menos um filtro: idAttendance, idContact ou phone.
errors.apis.queryTimeout
A consulta demorou mais que o permitido. Refine os filtros e tente novamente.
errors.apis.recordNotFound
Registro não encontrado.
errors.apis.tagNotFound
A etiqueta id não existe nesta empresa.
errors.apis.tagsRequired
Informe em tags a lista de identificadores das etiquetas.
errors.apis.whisperAuthorInvalid
O idUser deve ser de um administrador ou supervisor ativo da empresa.
errors.attendanceWhisper.alreadySent
Este sussurro já foi enviado.
errors.attendanceWhisper.attendanceClosed
O atendimento está encerrado e não aceita sussurros.
errors.attendanceWhisper.contentTooLong
O sussurro pode ter no máximo 4096 caracteres.
errors.attendanceWhisper.emptyContent
Escreva o texto do sussurro.
errors.chatAgent.agentInactive
O agente de integração está desativado.
errors.chatAgent.blockedFileType
O arquivo nome não é aceito: arquivos executáveis são bloqueados.
errors.chatAgent.channelDescriptionTooLong
A descrição do canal pode ter no máximo 240 caracteres.
errors.chatAgent.channelNameInvalid
Informe o nome do canal, com no máximo 80 caracteres.
errors.chatAgent.channelNameUnavailable
Este nome de canal não está disponível.
errors.chatAgent.channelUnavailable
Canal não encontrado ou indisponível para o agente.
errors.chatAgent.chatTemporarilyUnavailable
O chat interno não respondeu a tempo. Tente novamente em instantes.
errors.chatAgent.chatUnavailable
O chat interno não está disponível para esta empresa.
errors.chatAgent.clientIdInvalid
O clientId deve ser um texto de até 100 caracteres.
errors.chatAgent.emailListInvalid
O campo members ou mentions deve ser uma lista de e-mails.
errors.chatAgent.emptyMessage
Envie um texto ou ao menos um arquivo.
errors.chatAgent.fileTooLarge
Cada arquivo pode ter no máximo 10 MB.
errors.chatAgent.invalidEmail
O e-mail email não é válido.
errors.chatAgent.keyInvalid
Chave do agente de integração ausente ou inválida. Envie a chave no cabeçalho X-Agent-Key.
errors.chatAgent.messageNotFound
Mensagem não encontrada.
errors.chatAgent.rateLimited
Limite de 60 mensagens por minuto atingido. Tente novamente em segundos segundos.
errors.chatAgent.storageUnavailable
O envio de arquivos está indisponível no momento. Tente novamente mais tarde.
errors.chatAgent.textTooLong
O texto pode ter no máximo 12000 caracteres.
errors.chatAgent.threadNotFound
A mensagem indicada em thread não existe neste canal.
errors.chatAgent.tooManyEmails
Informe no máximo 100 e-mails por chamada.
errors.chatAgent.tooManyFiles
Envie no máximo 5 arquivos por mensagem.
errors.common.unexpected
Oops! Algo não saiu como esperado. Tente novamente!
errors.contact.notFound
Contato não encontrado.
errors.customer.notFound
Cliente não encontrado
Como tratar
4xx, menos 401 e 429: corrija a chamada. Repetir igual não resolve.
401: gere um token novo e repita a chamada uma vez. Se o corpo trouxer errors.chatAgent.keyInvalid, o problema é a chave do agente do chat interno, e um token novo não resolve.
429 e 503: espere os segundos do cabeçalho Retry-After e repita. No chat interno, repita com o mesmo clientId (Repetir sem duplicar).
500 e 504: repita com espera crescente, como 1, 2 e 4 segundos. No 504 da lista de mensagens, reduza perPage ou filtre por idAttendance.
200 com corpo vazio numa consulta por identificador: trate como registro não encontrado.
O que a API aceita em cada campo, quanto tempo uma consulta pode levar e onde ver o registro de cada chamada que o seu sistema fez.
No TrendmultiRelatórios›Relatório de APILeitura de 4 min
Volume de chamadas
A API não limita o número de chamadas por minuto, com uma exceção: cada agente de integração publica até 60 mensagens por minuto no chat interno (abaixo). Mesmo assim, reaproveite o token, evite consultas repetidas em intervalos curtos e prefira os webhooks de saída para saber quando algo muda.
Empresas em período de teste têm um limite total de chamadas definido no plano. Quando ele é atingido, a autenticação passa a ser recusada.
A lista de mensagens tem até 5 segundos por consulta. Passou disso, a resposta é 504.
Formatos
Identificadores
24 caracteres hexadecimais, como 6563f0c2a1b2c3d4e5f60718. Um valor fora do formato numa consulta responde como registro não encontrado; numa atualização, responde 404.
Telefones
Só dígitos, com DDI e DDD: 5511999998888. Na lista de mensagens por telefone, o nono dígito é opcional. No cadastro de contato, o telefone é gravado como foi enviado, e um telefone já cadastrado recusa o cadastro.
Até 60 por minuto por agente. Toda tentativa de publicar conta, inclusive as recusadas por dados inválidos. Passou disso, a resposta é 429 com o cabeçalho Retry-After. Listar canais, criar canais e excluir mensagens não contam.
Texto
Até 12.000 caracteres por mensagem.
Arquivos
Até 5 por mensagem, de até 10 MB cada. Arquivos executáveis são recusados.
E-mails
Até 100 por chamada, em members ou em mentions.
clientId
Até 100 caracteres.
Canais
Nome de até 80 caracteres e descrição de até 240. A lista de canais traz até 500.
Tempo de resposta
Até 10 segundos. Passou disso, a resposta é 503 com o cabeçalho Retry-After.
Registro das chamadas
Cada chamada que chega à API fica registrada no Trendmulti, com URL, data, método, canal e status, e os corpos da requisição e da resposta. Para consultar, abra Relatórios›Relatório de API (manual do usuário). É o primeiro lugar para olhar quando uma integração reclama de erro.
O cabeçalho de autorização, o Token do canal enviado em POST /api/auth, o token de acesso devolvido, o texto dos sussurros, a chave do agente (X-Agent-Key), o texto das mensagens publicadas no chat interno e os nomes dos arquivos enviados com elas não aparecem no registro: no lugar deles fica [REDACTED]. Uma publicação com arquivos fica registrada sem os campos do formulário.
Os webhooks de saída avisam o seu sistema quando algo acontece no canal: um atendimento abre, chega uma mensagem, uma mensagem de disparo é entregue. Em vez de consultar a API o tempo todo, você recebe o aviso na hora.
No TrendmultiCanais›abra o canal›WebhooksLeitura de 8 min
Configurar
No Trendmulti, abra Canais›abra o canal›Webhooks.
Clique em + Adicionar.
Informe um Nome que identifique o destino e a URL do seu sistema.
Escolha os eventos, deixe o webhook ativado e clique em Confirmar.
Um canal pode ter vários webhooks, cada um com a sua URL e os seus eventos. O passo a passo da tela está no manual do usuário.
Eventos
Na tela
Valor de event
Quando
Ao criar novo atendimento
ATTENDANCE_CREATE
Um atendimento é aberto.
Ao receber lead do Meta
ATTENDANCE_REFERRAL_CREATE
Um atendimento começa a partir de um anúncio do Meta.
Ao encerrar atendimento
ATTENDANCE_CLOSE
O atendimento é encerrado.
Ao receber nova mensagem
ATTENDANCE_NEW_MESSAGE
Chega uma nova mensagem no atendimento.
Ao transferir atendimento
ATTENDANCE_TRANSFER
O atendimento muda de atendente ou de departamento.
Ao enviar nova mensagem de disparo
CAMPAIGN_MESSAGE_SENT
O provedor aceitou a mensagem para envio.
Ao receber confirmação de entrega de mensagem de disparo
CAMPAIGN_MESSAGE_DELIVERED
O provedor confirmou a entrega.
Ao receber confirmação de leitura de mensagem de disparo
CAMPAIGN_MESSAGE_READ
O provedor confirmou a leitura.
Ao receber falha de envio de mensagem de disparo
CAMPAIGN_MESSAGE_FAILED
A mensagem foi recusada no envio, ou foi aceita e não pôde ser entregue.
Ao concluir disparo de campanha
CAMPAIGN_CONCLUDED
O disparo terminou: concluído, cancelado ou com erro.
Os eventos de disparo existem nos canais de WhatsApp, oficial e não oficial, e de RCS.
Como o aviso chega
Método
POST, com corpo JSON e o cabeçalho Content-Type: application/json.
Resposta esperada
Qualquer código 2xx, rápido. Nos eventos de disparo, o Trendmulti espera até 10 segundos.
Novas tentativas
Se a entrega falha, o aviso é enviado de novo, até 3 vezes.
Ordem
Os avisos podem chegar fora de ordem. Use a data de cada um: occurredAt nos disparos e updatedAt nos atendimentos.
Volume
Até 150 avisos de disparo ao mesmo tempo para o mesmo endereço. Um disparo grande gera até três avisos por contato: envio, entrega e leitura.
Formato: eventos de atendimento
Os cinco eventos de atendimento têm o mesmo formato. Campos sem valor não vêm no aviso.
DONE, CANCELED ou ERROR. Com ERROR, reason traz o motivo.
kpis
Os números da tela de detalhamento do disparo naquele momento. Entregues e lidas ainda podem crescer, porque as confirmações continuam chegando.
kpis.rates
Percentuais com duas casas, ou null quando ainda não há base para o cálculo.
cost
O custo do disparo, ou null. Com estimate: true, é uma estimativa pela tabela da Meta, na moeda dela; com false, é o valor cobrado da carteira, em reais.
Boas práticas
Responda 2xx assim que receber e processe depois, numa fila sua.
Trate avisos repetidos: com as novas tentativas, o mesmo aviso pode chegar mais de uma vez. Nos disparos, use event + message.id; nos atendimentos, event + protocol + updatedAt.
Aceite valores novos de event e de transfer.origin sem falhar.
O webhook de integração recebe dados do seu sistema, como o formulário do site, uma landing page ou o ERP, e executa as ações montadas na tela: cadastrar o contato, enviar uma mensagem, aplicar etiquetas, abrir atendimento ou criar uma oportunidade.
No TrendmultiIntegrações›WebhookLeitura de 4 min
Quando usar
Use o webhook de integração quando o Trendmulti deve reagir a um evento do seu sistema sem você programar cada passo. As ações ficam configuradas na tela, e o seu sistema só envia os dados.
Para controlar cada passo, como escolher o contato, o texto ou a etapa do funil na hora, use a API.
Configurar
No Trendmulti, abra Integrações›Webhook e clique em + Adicionar. A URL do Webhook aparece no topo.
Envie uma chamada de teste do seu sistema. Ela aparece no painel Requisições, e os campos dela viram opções nas ações.
Monte as ações e clique em Salvar.
Mude a chave ao lado da URL de Modo Teste para Funcionando.
O botão Gerar cURL copia um exemplo de chamada. O webhook de integração depende do módulo de webhook no plano. O passo a passo completo está no manual do usuário.
https://integrations.trendmulti.com.br/webhook/{código da empresa}/{identificador do webhook}/, exatamente como a tela mostra.
Método
Qualquer um. Use POST.
Corpo
JSON, application/x-www-form-urlencoded ou multipart/form-data com um arquivo no campo file. Os nomes dos campos são livres: você aponta na tela qual campo é o telefone, qual é o nome e assim por diante.
Autenticação
A própria URL. Quem a tiver consegue enviar dados: compartilhe só com quem vai integrar e não a publique em páginas abertas.
Respostas
Código
O que significa
200
A chamada foi registrada e as ações rodaram.
503
A chamada não pôde ser registrada e nada foi executado. Repita depois do tempo do cabeçalho Retry-After (30 segundos).
500
Erro ao executar as ações.
Toda chamada é registrada, mesmo quando nenhuma ação roda. Em período de teste, o número de chamadas recebidas é limitado.
Um agente de integração publica avisos dos seus sistemas nos canais públicos do chat interno da empresa: a falha de uma automação, um pipeline que parou, o resultado de uma rotina. A equipe recebe o aviso onde já conversa, como a mensagem de uma pessoa.
No TrendmultiChat interno›Agentes de integraçãoLeitura de 9 min
O que é um agente de integração
O agente é a identidade de um sistema no chat: um nome e uma imagem, como “Alertas do Airflow”. Um administrador da empresa cadastra o agente no chat interno, em Agentes de integração, e entrega a chave dele a quem integra. O passo a passo da tela está no manual do usuário.
Na conversa, as pessoas veem a mensagem com o nome e a imagem do agente e a marca Integração. Ela chega como a de uma pessoa: em tempo real, com contador de não lidas e alertas. O agente publica sem ser membro do canal.
O token de acesso de POST /api/auth, gerado com o UUID e o Token de um canal de atendimento conectado da empresa (Autenticação). Nas rotas do chat, o token vale pela empresa: qualquer canal conectado dela serve.
X-Agent-Key
A chave do agente, que começa com tmca_. Os administradores da empresa veem e copiam a chave a qualquer momento, em Agentes de integração. É ela que diz qual agente publica.
Gerar uma nova chave invalida a anterior na hora. Atualize a integração em seguida.
Chave ausente, desconhecida, de um agente removido ou de outra empresa: 401 com errors.chatAgent.keyInvalid, a mesma resposta em todos os casos.
Agente desativado: 403 com errors.chatAgent.agentInactive, até um administrador reativá-lo.
Chat interno inativo para a empresa: 403 com errors.chatAgent.chatUnavailable.
Token ausente, malformado ou vencido: 401 com o texto Unauthorized, como nas demais rotas.
Do token ao aviso, com cURL
Este roteiro cria o canal de alertas, publica um aviso com menção, responde na thread com o log e exclui uma mensagem. O primeiro passo usa o jq para ler o token.
O canal é público e mostra o agente como criador. Ana entrou como membro; x@empresa.com.br não é usuário ativo da empresa e voltou em notAdded. O agente não vira membro.
Se já existe um canal público ativo com esse nome, sem diferenciar maiúsculas de minúsculas, a resposta é 200 com esse canal e existed: true, e ninguém é adicionado. Por isso a chamada é segura em toda execução do seu sistema. Um nome em uso por um canal privado ou arquivado responde 409. Para achar um canal sem criar, use GET /chat/channels com name.
No canal, a menção aparece com o nome de Ana em destaque, “@Ana Souza”, e o texto sai com negrito e itálico. Guarde o id: ele serve para responder na thread e para excluir.
4 · Responda na thread, com o log
cURL
curl -X POST "https://apis.trendmulti.com.br/chat/channels/6740f2c1a9b3e45d12c0ffee/messages" \
-H "Authorization: Bearer $TRENDMULTI_TOKEN" \
-H "X-Agent-Key: $TRENDMULTI_AGENT_KEY" \
--form-string "text=Log da execução em anexo." \
--form-string "thread=6740f3d7a9b3e45d12c0f00d" \
--form-string "clientId=faturamento-diario-2026-11-21-log" \
-F "files=@faturamento.log;type=text/plain"
Com arquivos, a publicação vai em multipart/form-data, e o curl monta o corpo e o cabeçalho. Use --form-string nos campos de texto: no -F, um valor que começa com @ é lido como arquivo. A resposta traz um item para o arquivo e outro para o texto:
A resposta é {"id": "6740f3e2a9b3e45d12c0f010", "deleted": true}. Cada item é excluído pelo seu id: para tirar o arquivo e o texto, exclua os dois. A mensagem sai para todos os membros, como quando uma pessoa exclui a própria. O agente só exclui o que ele mesmo publicou; no chat, um administrador da empresa também pode excluir uma mensagem do agente.
Falhas do Airflow
No Airflow, um on_failure_callback roda quando uma tarefa termina com falha. Este exemplo publica o DAG, a tarefa, a execução e o link do log no canal de alertas, mencionando quem cuida do pipeline.
Python
import hashlib
import os
import requests
API = "https://apis.trendmulti.com.br"
def avisar_falha_no_chat(context):
ti = context["task_instance"]
auth = requests.post(
f"{API}/api/auth",
json={"uuid": os.environ["TRENDMULTI_UUID"], "token": os.environ["TRENDMULTI_CHANNEL_TOKEN"]},
timeout=10,
)
auth.raise_for_status()
# A mesma falha gera sempre o mesmo clientId (64 caracteres)
falha = f"{ti.dag_id}|{ti.run_id}|{ti.task_id}|{ti.try_number}"
client_id = hashlib.sha256(falha.encode()).hexdigest()
res = requests.post(
f"{API}/chat/channels/{os.environ['TRENDMULTI_CHAT_CHANNEL']}/messages",
headers={
"Authorization": f"Bearer {auth.json()['token']}",
"X-Agent-Key": os.environ["TRENDMULTI_AGENT_KEY"],
},
json={
"text": (
f"@ana@empresa.com.br falhou a tarefa `{ti.task_id}` do DAG **{ti.dag_id}**.\n"
f"Execução: `{ti.run_id}`\n"
f"[Abrir o log]({ti.log_url})"
),
"mentions": ["ana@empresa.com.br"],
"clientId": client_id,
},
timeout=15,
)
res.raise_for_status()
Ligue o callback a todas as tarefas do DAG pelos default_args:
Python
from datetime import datetime
from airflow import DAG
with DAG(
dag_id="faturamento_diario",
schedule="@daily",
start_date=datetime(2026, 11, 1),
default_args={"on_failure_callback": avisar_falha_no_chat},
) as dag:
...
O exemplo lê quatro variáveis de ambiente: TRENDMULTI_UUID e TRENDMULTI_CHANNEL_TOKEN, as credenciais do canal de atendimento; TRENDMULTI_AGENT_KEY, a chave do agente; e TRENDMULTI_CHAT_CHANNEL, o id do canal do chat. Guarde os valores como segredos do ambiente, nunca no código do DAG.
O clientId sai de dag_id, run_id, task_id e da tentativa. Repetir a chamada pela mesma falha devolve a mensagem já publicada, e uma nova execução da tarefa que falhe de novo gera outro aviso. O hash cabe no limite de 100 caracteres.
Num 503, repita a mesma chamada, com o mesmo clientId, depois dos segundos do cabeçalho Retry-After (Repetir sem duplicar).
O exemplo gera um token a cada aviso, o que basta para avisos de falha. Se o volume for alto, reaproveite o token por até 24 horas.
No n8n
No n8n, use dois nós HTTP Request. Os nomes abaixo são os da interface do n8n, em inglês.
Autenticar. Dê esse nome ao primeiro nó, com MethodPOST, URLhttps://apis.trendmulti.com.br/api/auth e, em Send Body, o JSON com uuid e token do canal de atendimento. A resposta traz o token no campo token.
Publicar. No segundo nó, MethodPOST e URLhttps://apis.trendmulti.com.br/chat/channels/{id}/messages, com o id do canal. Ligue Send Headers e envie Authorization com o valor Bearer {{ $('Autenticar').item.json.token }} e X-Agent-Key com a chave do agente. Em Send Body, escolha JSON e envie text, mentions e clientId.
Use {{ $execution.id }} no clientId. Com Retry On Fail ligado nas configurações do nó, as novas tentativas repetem o mesmo valor e não duplicam a mensagem. Se o fluxo publica mais de uma mensagem por execução, acrescente um sufixo, como {{ $execution.id }}-resumo.
Para não deixar a chave à mostra no nó, crie uma credencial Header Auth com o nome X-Agent-Key e escolha-a em Authentication › Generic Credential Type.
Para enviar um arquivo, mude o corpo para Form-Data e adicione um campo do tipo n8n Binary File com o nome files.
Texto e arquivos
O texto aceita até 12.000 caracteres e a formatação leve do chat:
Escreva
Para
**texto**
Negrito
_texto_
Itálico
__texto__
Sublinhado
~~texto~~
Tachado
[texto](https://…)
Link
`código`
Código na linha
``` antes e depois do trecho
Bloco de código
Linhas que começam com 1. ou -
Lista numerada ou com marcadores
Endereços que começam com http:// ou https:// viram link sozinhos, e as quebras de linha são mantidas. Tags HTML são removidas do texto. Nomes técnicos ficam melhores entre crases, como `faturamento_diario`: dentro do código, nada vira formatação.
Arquivos
Para enviar arquivos, mande a publicação em multipart/form-data: os arquivos no campo files e os demais campos como campos do formulário. São até 5 arquivos por mensagem, de até 10 MB cada. Arquivos executáveis (.exe, .bat, .sh, .cmd, .msi, .com e .scr) são recusados, e a mensagem inteira volta com erro.
Cada arquivo e o texto viram itens separados no canal, publicados nesta ordem: os arquivos, depois o texto. A resposta lista todos em items, com o tipo de cada um: TEXT para o texto e, conforme o tipo do arquivo enviado, IMAGE, AUDIO, VIDEO ou DOCUMENT. O id da resposta é o do texto, ou o do primeiro arquivo quando não há texto.
Menções
Liste em mentions os e-mails das pessoas a mencionar, até 100.
Escreva @email no texto onde cada menção deve aparecer. O chat troca pelo @Nome da pessoa, com destaque.
Só membros do canal viram menção. Os outros e-mails voltam em notMentioned, com o motivo: NOT_A_USER, quando não é usuário ativo da empresa, ou NOT_A_MEMBER, quando é usuário mas não é membro do canal. O @email deles fica no texto como foi escrito.
Uma menção da lista que não aparece no texto entra no começo dele. No exemplo, se Carlos é membro do canal, a mensagem começa com “@Carlos Lima @Ana Souza”.
Quem foi mencionado e não está conectado recebe uma notificação push, conforme as preferências dele. Sem menção, a mensagem notifica como a de uma pessoa: conta como não lida e gera o alerta no Trendmulti, conforme as preferências de cada membro, sem push.
Em multipart/form-data, repita o campo mentions com um e-mail em cada, ou envie a lista em JSON num campo só.
Respostas em thread
Para responder na thread de uma mensagem do canal, envie o id dela em thread. A resposta aparece na thread, e a mensagem original mostra quantas respostas tem e a hora da última.
A mensagem precisa ser do mesmo canal. Se não for, ou se ela não existir mais, a resposta é 400 com errors.chatAgent.threadNotFound.
Se o id for de uma resposta de thread, a nova mensagem vai para a thread da mensagem original.
Use a thread para manter juntos os avisos de um mesmo incidente: o primeiro aviso no canal e, dentro dele, o log, a nova tentativa e a volta ao normal.
Repetir sem duplicar
Envie em clientId um valor único por mensagem, gerado pelo seu sistema, com até 100 caracteres: o id do job, da execução ou do evento. Se a resposta não chegar, repita a chamada com o mesmo clientId:
Se a mensagem já foi publicada, nada é publicado de novo. A resposta, com status 200, traz a mensagem da primeira vez, com os mesmos identificadores.
Se a primeira chamada foi recusada com um erro 4xx, nada foi publicado, e o mesmo clientId pode ser usado de novo.
Cada agente tem os próprios clientId: o mesmo valor em dois agentes publica duas mensagens.
Um clientId já usado devolve sempre a primeira mensagem, mesmo depois de ela ser excluída ou de o canal ser arquivado. Use um valor novo para cada mensagem nova.
Um 503 com errors.chatAgent.chatTemporarilyUnavailable não garante que nada foi publicado: o chat pode publicar a mensagem logo depois. Espere os segundos do cabeçalho Retry-After e repita com o mesmo clientId. Faça o mesmo quando a sua chamada passar do tempo sem resposta.
Limites
Publicações
Até 60 por minuto por agente, em janelas de 60 segundos contadas a partir da primeira publicação. Toda tentativa de publicar conta, inclusive as recusadas por dados inválidos. Passou do limite: 429 com errors.chatAgent.rateLimited e o cabeçalho Retry-After. Listar canais, criar canais e excluir mensagens não contam.
Texto
Até 12.000 caracteres.
Arquivos
Até 5 por mensagem, de até 10 MB cada. Executáveis são recusados.
E-mails
Até 100 por chamada, em members ou em mentions.
clientId
Até 100 caracteres.
Canais
Nome de 1 a 80 caracteres e descrição de até 240. A lista traz até 500 canais, por ordem de nome.
Tempo de resposta
O chat tem até 10 segundos para responder. Passou disso, a resposta é 503 com Retry-After.
Erros
As respostas de erro seguem o formato da API, com a mensagem em português e a key. Os erros de acesso estão em As duas credenciais; os demais:
Código
Chave, quando acontece e o que fazer
400
errors.apis.invalidId O id do canal, de thread ou da mensagem não tem 24 caracteres hexadecimais. Corrija o identificador.
400
errors.chatAgent.* Dados fora das regras: nome ou descrição do canal, e-mails, texto vazio ou longo demais, clientId, arquivos demais ou executáveis, thread que não é deste canal. A mensagem diz o limite. Corrija a chamada: repetir igual não resolve.
404
errors.chatAgent.channelUnavailable O canal não existe, é privado, está arquivado, é de outra empresa ou é uma conversa direta ou em grupo. A resposta é a mesma em todos os casos. Use um id de GET /chat/channels.
404
errors.chatAgent.messageNotFound Na exclusão: a mensagem não existe, já foi excluída ou não foi publicada por este agente. Confira o id do item.
409
errors.chatAgent.channelNameUnavailable O nome é de um canal privado ou arquivado. Escolha outro nome.
413
errors.chatAgent.fileTooLarge Um arquivo passa de 10 MB. Compacte ou divida o arquivo.
429
errors.chatAgent.rateLimited O agente passou de 60 publicações no minuto. Espere os segundos do cabeçalho Retry-After.
503
errors.chatAgent.chatTemporarilyUnavailable O chat não respondeu em 10 segundos, ou ainda processa um pedido igual: o mesmo clientId, ou a criação de um canal com o mesmo nome. Espere os segundos do cabeçalho Retry-After e repita, com o mesmo clientId.
503
errors.chatAgent.storageUnavailable O envio de arquivos está indisponível; publicações sem arquivo continuam funcionando. Tente mais tarde, ou publique sem o arquivo.
500
errors.common.unexpected Erro inesperado no chat; raramente, a mesma chave vem com 400. Repita uma vez, com o mesmo clientId. Se persistir, fale com o suporte.
Todas as chaves, com as mensagens, estão em Chaves de erro.
O contrato da API em um arquivo, para importar nas suas ferramentas ou entregar a um assistente de código, e o atalho para consultar a conta em linguagem natural.
Arquivo/openapi.jsonLeitura de 3 min
Contrato OpenAPI (JSON e YAML)
Todas as rotas, parâmetros e modelos da API estão num contrato OpenAPI 3.0, que a própria API publica. É ele que gera a referência desta documentação. Use o endereço direto para levar a API ao Postman, ao Insomnia ou a uma IA:
No Postman, clique em Import e cole o endereço da coleção, ou arraste o arquivo baixado.
Abra a coleção Trendmulti API, aba Variables. Preencha channelUuid e channelToken com as credenciais de API de um canal conectado e, para as rotas do chat interno, agentKey com a chave do agente (As duas credenciais).
Execute Autenticação › POST /api/auth. O token devolvido vai sozinho para bearerToken e vale para as outras requisições por 1 dia.
Chame as outras rotas. As do chat interno já enviam o cabeçalho X-Agent-Key com {{agentKey}}; a publicação de mensagens tem uma versão (com arquivos), em multipart/form-data.
Prefere importar pelo contrato? Em Import, cole o endereço do JSON. A coleção criada assim usa {{bearerToken}} na autorização e {{agentKey}} no cabeçalho das rotas do chat interno: crie essas duas variáveis na aba Variables. No Insomnia, importe pelo endereço ou pelo arquivo do contrato. Quando a API ganhar uma rota nova, importe de novo para atualizar.
Numa IA
Entregue o endereço do JSON ou do YAML, ou o arquivo, ao assistente e peça a integração que você precisa, por exemplo: “Usando o contrato em https://apis.trendmulti.com.br/-json, escreva uma função que autentica e envia uma mensagem de texto para um contato”. O contrato traz rotas, campos e tipos; os guias desta documentação trazem as regras que ele não diz, como a validade do token e a paginação.
Swagger
O Swagger em apis.trendmulti.com.br mostra o mesmo contrato e deixa você testar as rotas. Gere o token com POST /api/auth e informe-o em Authorize. Para as rotas do chat interno, informe ali também a chave do agente, em agentKey.
Assistentes de código
Ao pedir a um assistente de código uma integração com o Trendmulti, entregue o contrato como contexto: o endereço https://apis.trendmulti.com.br/-json ou o arquivo. O arquivo llms.txt resume esta documentação para ferramentas de IA, com as regras que o contrato não diz, e aponta para o contrato.
Clientes de IA (MCP)
Para consultar a conta em linguagem natural, sem programar, o Trendmulti tem um conector para Claude, ChatGPT e outros clientes compatíveis com MCP, no endereço https://mcp.trendmulti.com.br/mcp.
Ele é diferente da API: cada pessoa entra com o próprio usuário do Trendmulti, vê só o que já vê na plataforma e não altera nada. O acesso é ativado por empresa; veja como no manual do usuário.
Status e suporte
A disponibilidade da plataforma aparece na página de status. Para dúvidas sobre a sua integração, fale com o suporte pelo link Suporte no rodapé do Trendmulti.
As mudanças da API e dos webhooks que afetam quem integra, das mais recentes para as mais antigas.
Dezembro de 2026
Chat interno por agentes de integração. Seus sistemas publicam avisos nos canais públicos do chat interno da empresa como um agente de integração, que um administrador cadastra no chat. As rotas pedem o token e a chave do agente no cabeçalho X-Agent-Key: GET /chat/channels lista os canais públicos, POST /chat/channels cria um canal ou devolve o que já existe, POST /chat/channels/{id}/messages publica texto, arquivos, menções e respostas em thread, e DELETE /chat/messages/{id} exclui uma mensagem do agente. Cada agente publica até 60 mensagens por minuto (guia).
Coleção Postman pronta. A coleção traz todas as rotas com as variáveis channelUuid, channelToken, bearerToken e agentKey e grava sozinha o token devolvido por POST /api/auth. O contrato OpenAPI passa a declarar o cabeçalho X-Agent-Key nas rotas do chat interno, e assim ele vem junto também quando você importa pelo contrato.
Sussurro por integração.POST /attendance/{id}/whisper cria um sussurro, a nota interna que a equipe vê no atendimento e o cliente nunca recebe. Com idUser de um administrador ou supervisor da empresa, sai em nome dessa pessoa; sem ele, aparece como Integração. A API não lista nem altera sussurros.
Campos personalizados do contato.POST /contact/create e PUT /contact/update aceitam customFields ({ id, value }), com os campos que GET /custom-field/list devolve. Na atualização, só os campos enviados mudam, e null apaga um valor. Etiquetas do contato que não são da empresa passam a ser ignoradas.
Eventos de disparo nos webhooks de saída.CAMPAIGN_MESSAGE_SENT, CAMPAIGN_MESSAGE_DELIVERED, CAMPAIGN_MESSAGE_READ, CAMPAIGN_MESSAGE_FAILED e CAMPAIGN_CONCLUDED (formato).
Autenticação mais rígida. UUID e Token precisam ser texto de 1 a 256 caracteres; fora disso, ou errados, a resposta é 401 com errors.apis.invalidCredentials. Todas as rotas, inclusive as do CRM, verificam o token. Consultas e atualizações por identificador ficam restritas à empresa do token. O token de acesso deixou de carregar as credenciais do canal.
Nova documentação. A referência passou a ser gerada a partir do contrato publicado pela API em produção, com guias, exemplos em quatro linguagens e a Trina.
Outubro de 2026
Filtros na lista de mensagens.GET /message/pager passou a aceitar idContact, phone e status, além de idAttendance, com validação de page e perPage (máximo 100) e limite de 5 segundos por consulta.
Clientes do CRM com dados da empresa. O cadastro de clientes aceita razão social, nome fantasia, CPF ou CNPJ, inscrição estadual, site, Instagram, segmento, porte, endereço e o código do cliente no seu ERP (referência).
Setembro de 2026
Evento de transferência. O webhook de saída ganhou o evento ATTENDANCE_TRANSFER, com o bloco transfer (formato).
Esc
↑ ↓ navegarEnter abrir
T
TrinaAssistente da documentação da API
A Trina responde com trechos desta documentação e mostra de onde tirou cada resposta.