--- title: "Conexão Universal" description: "Documentação ensinando fazer uma conexão universal" url: https://help.datacrazy.io/pt-br/articles/10670831-conexao-universal collection: "Conexões" updated: 2026-11-02 language: pt-br alternates: [en, es] --- # Conexão Universal Documentação ensinando fazer uma conexão universal A Conexão Universal permite integrar o CRM Datacrazy a qualquer serviço externo que disponibilize uma API ou webhook para envio e recebimento de mensagens. A configuração é dividida em duas partes: - Envio: define como o CRM deve chamar a API externa para enviar mensagens. - Recebimento: define como o CRM deve interpretar os webhooks enviados pela API externa quando uma mensagem for recebida. A conexão também permite configurar endpoints específicos para diferentes tipos de mídia, como imagens, vídeos, áudios e documentos. ## **1\. Envio** A seção Envio define como o CRM realizará uma requisição para a API ou webhook responsável pelo envio das mensagens. ### **URL Base** URL do endpoint que será chamado pelo CRM para realizar o envio da mensagem. Exemplo: [https://api.exemplo.com/messages](https://api.exemplo.com/messages) A URL pode utilizar variáveis disponíveis na conexão, incluindo credenciais: [https://api.exemplo.com/${credentials.apiEndpoint}](https://api.exemplo.com/${credentials.apiEndpoint}) ### **Método** Define o método HTTP utilizado na requisição. Os métodos mais comuns são: - POST - GET - PUT - PATCH - DELETE Para envio de mensagens, normalmente é utilizado: - POST ### **Caminho** Define o caminho/rota utilizado para o envio de mensagens de texto. Exemplo: /messages/send Quando combinado com a URL base: [https://api.exemplo.com/messages/send](https://api.exemplo.com/messages/send) ### **Template do Body** Define o corpo JSON que será enviado para a API externa. O template pode utilizar variáveis dinâmicas fornecidas pelo CRM. ### **Variáveis disponíveis**

Variável

Descrição

${contact.contactId}                       Identificador do contato ${[contact.name](https://contact.name)}                            Nome do contato ${message.body}                            Conteúdo da mensagem ${[credentials.xxx](https://credentials.xxx)}                         Valor de uma credencial cadastrada Exemplo: { "phone": "${contact.contactId}", "name": "${[contact.name](https://contact.name)}", "message": "${message.body}" } As variáveis são substituídas pelo CRM no momento da execução da requisição. ### **Content-Type** Define o tipo de conteúdo enviado no corpo da requisição. O formato mais utilizado é: application/json Exemplo: Content-Type: application/json A configuração deve corresponder ao formato esperado pela API externa. ### **Timeout (ms)** Define o tempo máximo, em milissegundos, que o CRM aguardará pela resposta da API. Exemplo: 5000 Nesse caso, o CRM aguardará até 5 segundos pela resposta da requisição. Se a API não responder dentro do período configurado, a requisição será considerada como falha. ## **2\. Autenticação** A autenticação define como o CRM deverá enviar as credenciais necessárias para acessar a API externa. ### **Tipos disponíveis** ### **Nenhuma** Nenhuma informação de autenticação será adicionada automaticamente à requisição. Utilizado quando o endpoint não exige autenticação. ### **Bearer Token** Adiciona um token de autenticação no header da requisição. Exemplo: Authorization: Bearer SEU\_TOKEN ### **API Key** Utilizado quando a API exige uma chave de acesso. A chave pode ser enviada no header conforme a configuração da API. Exemplo: X-API-Key: SUA\_API\_KEY ### **Basic Auth** Utiliza autenticação HTTP Basic, normalmente baseada em usuário e senha. Exemplo: Authorization: Basic ### **Headers Customizados** Permite configurar manualmente os headers utilizados pela API. É útil quando o serviço externo utiliza um formato de autenticação específico. ## **3\. Credenciais** A seção Credenciais permite armazenar valores sensíveis que serão utilizados nas requisições. Podem ser armazenados: - Tokens - API Keys - Senhas - Segredos - URLs - Outros valores necessários para a integração ### **Cada credencial possui:** Nome da variável Valor Exemplo: Nome: apiToken Valor: abc123xyz A credencial pode ser utilizada nos campos da conexão através da variável: ${credentials.apiToken} Ela pode ser utilizada em: - URL - Headers - Body - Parâmetros de Query Exemplo: { "token": "${credentials.apiToken}", "message": "${message.body}" } Recomenda-se utilizar credenciais para informações sensíveis em vez de inserir tokens diretamente nos templates. ## **4\. Headers** Permite adicionar headers personalizados à requisição de envio. ### **Cada header possui:** Nome Valor Exemplo: Nome: X-API-Key Valor: ${credentials.apiKey} Os headers podem ser utilizados quando: A API exige informações específicas; Existe um middleware entre o CRM e a API; A autenticação utiliza um formato personalizado; A API exige identificadores adicionais. ## **5\. Parâmetros de Query** Permite configurar parâmetros que serão enviados na URL da requisição. Exemplo: [https://api.exemplo.com/messages?instance=123](https://api.exemplo.com/messages?instance=123) ### **Configuração:** Nome: instance Valor: 123 Também é possível utilizar credenciais: Nome: token Valor: ${credentials.apiToken} ## **6\. Mapeamento de Resposta** Após realizar o envio, a API externa deve retornar um payload JSON. O CRM utiliza esse payload para identificar: 1. 1\. O ID da mensagem enviada; 2. 2\. Se o envio foi realizado com sucesso. ### **Caminho do ID da Mensagem** Define o caminho dentro do JSON onde está localizado o identificador da mensagem. Exemplo de resposta: { "success": true, "message": { "id": "abc123" } } ### **Configuração:** Caminho do ID da Mensagem: [message.id](https://message.id) ### **Caminho do Sucesso** Define o caminho dentro do JSON que informa se a operação foi realizada com sucesso. Exemplo: { "success": true, "message": { "id": "abc123" } } ### **Configuração:** Caminho do Sucesso: success O CRM considera a resposta bem-sucedida quando o valor encontrado no caminho configurado corresponde a um valor válido de sucesso. São considerados valores de sucesso: - true - 1 - Valores numéricos maiores que 0 - A string "1" Valores diferentes desses são considerados falha. Exemplo: { "success": false } Resultado: Falha no envio ## **7\. Testar Conexão** O botão Testar conexão executa uma requisição utilizando a configuração atual da conexão. O teste verifica se o endpoint está acessível e se a requisição consegue ser processada. ### **Resultado de sucesso** Quando o endpoint retorna HTTP: 200 o teste é considerado bem-sucedido. ### **Resultado de erro** Caso a API retorne outro status HTTP ou ocorra uma falha durante a requisição, o teste será considerado inválido. Os detalhes da execução podem ser consultados na aba Logs. Os logs ajudam a identificar problemas como: URL incorreta; Token inválido; Header incorreto; Body inválido; - Timeout; Erro retornado pela API externa. ## **8\. Endpoints Adicionais** Os Endpoints Adicionais permitem configurar rotas específicas para diferentes tipos de mídia. Isso é útil quando uma API possui endpoints diferentes para: - Imagens - Vídeos - Áudios - Documentos - Outros anexos Cada endpoint adicional possui sua própria configuração de: - Método; - Caminho; - Template do Body; - Content-Type; - Timeout; - Headers; Parâmetros de Query. ### **Tipos de mídia** Ao configurar um endpoint adicional, é possível definir quais tipos de mídia deverão utilizar aquela rota. Por exemplo: Tipos de mídia: Imagem Vídeo Documento Quando o CRM precisar enviar uma mídia desse tipo, ele utilizará automaticamente o endpoint correspondente. ### **Exemplo** Uma conexão pode possuir: POST /messages/text para mensagens de texto e: POST /messages/media para imagens, vídeos e documentos. Ao enviar uma imagem pelo CRM, a rota /messages/media será utilizada automaticamente. ## **9\. Variáveis para Mídia** Os templates de endpoints de mídia possuem variáveis específicas.

Variável

Descrição

${attachment.url}                                         URL do arquivo ${attachment.mimeType}                                    MIME type do arquivo ${attachment.fileName}                                    Nome do arquivo Exemplo: { "url": "${attachment.url}", "mimeType": "${attachment.mimeType}", "fileName": "${attachment.fileName}", "phone": "${contact.contactId}" } ### **Exemplo de MIME type** Uma imagem JPEG normalmente possui: image/jpeg Um PDF: application/pdf Um vídeo MP4: video/mp4 O MIME type enviado deve corresponder ao formato real do arquivo e ao formato aceito pela API externa. ## **10\. Recebimento** A seção Recebimento define como o CRM receberá e interpretará mensagens enviadas pela API externa. ### **Habilitar recebimento de mensagens** O toggle Habilitar recebimento de mensagens determina se a conexão utilizará o sistema de recebimento de mensagens. Quando habilitado, o CRM disponibiliza um webhook para que o serviço externo envie os eventos de mensagens recebidas. ## **11\. Mapeamento de Campos** Cada mensagem recebida pelo CRM possui um payload enviado pela API externa. O Mapeamento de Campos informa ao CRM onde encontrar cada informação dentro desse payload. A estrutura do payload pode variar de acordo com o serviço integrado. Por isso, é necessário informar o caminho correto de cada campo. ### **Caminho do ID do Contato** Define onde está localizado o identificador do contato no payload recebido. Esse valor é utilizado para identificar com qual contato/conversa a mensagem está relacionada. Exemplo: { "data": { "contact": { "id": "5511999999999" } } } ### **Configuração:** [data.contact.id](https://data.contact.id) ### **Caminho do Corpo da Mensagem** Define onde está localizado o conteúdo textual da mensagem. Exemplo: { "message": { "body": "Olá, tudo bem?" } } ### **Configuração:** message.body ### **Caminho do ID da Mensagem** Define onde está localizado o identificador único da mensagem recebida. Exemplo: { "message": { "id": "ABC123" } } ### **Configuração:** [message.id](https://message.id) Esse identificador é utilizado pelo CRM para identificar a mensagem recebida. ### **Caminho do Nome do Contato** Define onde está localizado o nome do contato no payload. Exemplo: { "contact": { "name": "Carlos" } } ### **Configuração:** [contact.name](https://contact.name) ### **Caminho do Timestamp** Define onde está localizada a data e hora em que a mensagem foi recebida. Exemplo: { "message": { "timestamp": "2026-09-21T14:30:00Z" } } ### **Configuração:** message.timestamp O timestamp deve representar a data e hora da mensagem recebida. ### **Caminho do ID Externo da Mensagem** Campo opcional utilizado quando a API possui um identificador externo adicional para a mensagem. Exemplo: { "message": { "id": "internal-id", "externalId": "external-id" } } ### **Configuração:** message.externalId Caso a API não possua um ID externo separado, pode ser utilizado o mesmo caminho configurado para o ID da mensagem. ### **Caminho da URL do Anexo** Define onde está localizada a URL do arquivo quando a mensagem contém uma mídia. Exemplo: { "attachment": { "url": "[https://cdn.exemplo.com/image.jpg](https://cdn.exemplo.com/image.jpg)" } } ### **Configuração:** attachment.url ### **Caminho do Tipo do Anexo** Define onde está localizado o MIME type do arquivo recebido. Exemplo: { "attachment": { "mimeType": "image/jpeg" } } ### **Configuração:** attachment.mimeType O MIME type deve corresponder ao tipo real do arquivo. Uma configuração incorreta pode fazer com que mídias recebidas sejam interpretadas ou processadas incorretamente pelo CRM. ### **Caminho do From Me** Define onde está localizado o campo booleano que informa se a mensagem foi enviada pelo próprio usuário/sistema. Exemplo: { "message": { "isFromMe": true } } ### **Configuração:** message.isFromMe O valor esperado deve ser booleano: - true - false Esse campo é utilizado principalmente para diferenciar mensagens recebidas de mensagens enviadas pelo próprio sistema. ## **12\. Validação do Webhook** A validação do webhook permite verificar se uma requisição recebida realmente foi enviada por uma fonte autorizada. A validação é opcional. ### **Header de Assinatura** Define o nome do header utilizado para transportar a assinatura. Exemplo: X-Signature ### **Segredo de Validação** Define o segredo utilizado para validar a autenticidade da requisição. Esse valor deve ser mantido em segurança e, quando aplicável, deve corresponder ao segredo configurado no serviço externo. ### **Algoritmo de Validação** Define o método utilizado para validar a assinatura. ### **SHA-256** Algoritmo criptográfico que produz um hash de 256 bits. É utilizado para gerar uma representação criptográfica dos dados. ### **SHA-1** Algoritmo de hash mais antigo, com 160 bits. É mantido principalmente para compatibilidade com sistemas legados e não é recomendado para novos sistemas quando existem alternativas mais seguras. ### **HMAC-SHA256** Utiliza SHA-256 combinado com uma chave secreta compartilhada. É uma opção comum para autenticação de webhooks porque permite verificar se o payload foi enviado por quem possui o segredo. ### **Static Token** Utiliza um token fixo para validação. Exemplo: X-Webhook-Token: meu-token É uma alternativa simples para APIs que não utilizam assinaturas criptográficas. ## **13\. Filtros** Os filtros permitem definir condições mínimas para que um webhook seja processado pelo CRM. ### **Campo Obrigatório** Define o caminho de um campo que obrigatoriamente deve existir no payload. Exemplo: [message.id](https://message.id) Se o campo não existir no payload recebido, o CRM não processará o evento como uma mensagem. Isso pode ser utilizado para evitar que eventos que não representam mensagens sejam processados. ### **Ignorar Mensagens Próprias** Permite ignorar mensagens enviadas pelo próprio sistema. Para isso, deve ser informado o caminho do campo booleano que identifica se a mensagem foi enviada pelo próprio sistema. Exemplo: message.isFromMe Se o valor encontrado nesse caminho for: - true o CRM ignora a mensagem como uma nova mensagem recebida do contato. ## **14\. URL do Webhook** Quando o recebimento de mensagens está habilitado, o CRM gera uma URL exclusiva para a conexão. O formato é semelhante a: [https://messaging.g1.datacrazy.io/webhooks/universal/{instance\_id}/{webhook\_id}](https://messaging.g1.datacrazy.io/webhooks/universal/{instance_id}/{webhook_id}) A URL gerada deve ser configurada no serviço externo responsável por enviar os eventos de mensagens. Quando uma mensagem for recebida no serviço externo, ele deverá realizar uma requisição para essa URL, enviando o payload da mensagem. ### **Exemplo** POST [https://messaging.g1.datacrazy.io/webhooks/universal/instance\_id/webhook\_id](https://messaging.g1.datacrazy.io/webhooks/universal/instance_id/webhook_id) Content-Type: application/json ### **Body:** { "message": { "id": "123456", "body": "Olá!" }, "contact": { "id": "5511999999999", "name": "Carlos" } } O CRM utilizará o Mapeamento de Campos configurado na conexão para interpretar esse payload. ## **15\. Botão Webhook** O botão Webhook abre o modal de configuração do webhook de recebimento. Nesse modal são disponibilizadas: URL do Webhook A URL gerada automaticamente para a conexão. Essa é a mesma URL apresentada na seção Recebimento. Token de Verificação Campo opcional utilizado quando o serviço externo exige um token para validar o webhook. O token deve ser configurado de acordo com as regras da API externa. ## **16\. Finalizar** O botão Finalizar salva a configuração da Conexão Universal. Após finalizar, a conexão poderá ser utilizada pelo CRM de acordo com os recursos configurados: - Envio de mensagens; - Envio de mídias; - Recebimento de mensagens; - Autenticação; - Mapeamento de respostas; - Validação de webhook. ## **17\. Remover** O botão Remover exclui a instância da Conexão Universal do CRM. Após a remoção, a configuração da conexão deixa de estar disponível para utilização no CRM.