Como Criar Cadastro na Uzapi

Ao acessar a plataforma, escolha uma das opções de login:

• Cadastro com e-mail
• Login com Google

Cadastro com e-mail

Para criar sua conta com e-mail:

1. Preencha todos os campos obrigatórios
2. Aceite os termos de uso
3. Finalize o cadastro

Login com Google

Para entrar com sua conta Google:

1. Faça login com sua conta Google
2. Informe:
   • Nome de usuário (username)
   • Número de WhatsApp
3. Insira o código de verificação enviado

OBS: Cadastro para não residentes no Brasil

No momento, não estamos aceitando cadastros de clientes que residem fora do Brasil devido a limitações relacionadas ao nosso gateway de pagamento e ao sistema de SMS utilizado para a ativação da conta.

Em breve, atualizaremos nossos sistemas para possibilitar o cadastro e a ativação de contas para clientes residentes em outros países.

Login com Google

Para entrar com sua conta Google:

1. Faça login com sua conta Google
2. Informe:
   • Nome de usuário (username)
   • Número de WhatsApp
3. Insira o código de verificação enviado

Descrição:
O onboarding nos ajuda a entender melhor nossos clientes, seus segmentos de atuação e o perfil do público atendido.

Dados da empresa

Preencha corretamente:

• Segmento de atuação da empresa
• Perfil dos seus clientes
• Tamanho da empresa
• Como conheceu a plataforma

Como você pretende usar a Uzapi

Informe:

• Seu objetivo principal com a plataforma
• Funcionalidades mais importantes para seu uso
• Principais atividades realizadas no dia a dia
• Tipo de mensagens que deseja enviar

Perfil dos seus clientes

• Segmentos atendidos
• Principais dores e necessidades

Explorando o Dashboard da Plataforma

Descrição:
O Dashboard é a página inicial da plataforma, onde você encontra um resumo completo das principais informações da sua conta e das suas instâncias. Ele permite acompanhar dados importantes de forma rápida e centralizada.

A seguir, veja os principais indicadores disponíveis:

1. Número de instâncias contratadas

Descrição:
Exibe o total de instâncias contratadas no seu plano, incluindo quantas estão ativas e em uso no momento.

2. Números conectados

Descrição:
Mostra a quantidade de números de WhatsApp atualmente conectados à plataforma através das instâncias ativas.

3. Status da assinatura

Descrição:
Informa a situação atual da sua assinatura, como:

• Ativa
• Teste
• Cancelada

Esse indicador é importante para garantir que seus serviços estejam funcionando corretamente.

4. Mensalidade

Descrição:
Apresenta o valor atual do seu plano contratado, permitindo fácil visualização dos custos recorrentes da plataforma.

5. Status das instâncias

Descrição:
Exibe o status detalhado de todas as instâncias cadastradas, como:

• Conectada
• Desconectada
• Aguardando autenticação

Esse painel ajuda no monitoramento e na gestão das conexões com o WhatsApp.

Dicas de Uso do Dashboard

• Acesse o Dashboard regularmente para acompanhar o status das suas instâncias
• Verifique se todas as conexões estão ativas para evitar falhas no envio de mensagens
• Monitore sua assinatura para evitar interrupções no serviço

Como Contratar, Fazer Upgrade e Downgrade de Instâncias na Uzapi

Descrição:
Nesta seção, você aprenderá como contratar novas instâncias, além de realizar upgrade ou downgrade do seu plano de forma automática dentro da plataforma Uzapi.

1. Como contratar novas instâncias

Siga o passo a passo abaixo para contratar novas instâncias:

1. No menu lateral, clique em Contratar instância
2. Selecione o plano desejado
3. Informe a quantidade de números/instâncias que deseja contratar
4. Clique em Contratar agora
5. Preencha os dados solicitados
6. Escolha o tipo de cobrança
7. Clique em Pagar primeira mensalidade
8. Selecione a forma de pagamento
9. Preencha os dados e confirme o pagamento

2. Como fazer upgrade de plano

O upgrade permite aumentar a quantidade de instâncias ou mudar para um plano superior.

1. No menu lateral, clique em Contratar instância
2. Selecione a nova quantidade de números/instâncias desejadas
3. Clique em Contratar agora
4. Escolha o tipo de cobrança
5. Clique em Pagar

Observação:
Será gerado um novo boleto com o valor proporcional referente à diferença entre o plano atual e o novo plano.

6. Selecione a forma de pagamento
7. Preencha os dados e confirme o pagamento

3. Como fazer downgrade de plano

O downgrade permite reduzir a quantidade de instâncias contratadas.

1. No menu lateral, clique em Contratar instância
2. Selecione a nova quantidade de instâncias desejadas (menor que a atual)
3. Clique em Contratar agora

Observação:

• Será calculada a diferença entre o plano atual e o novo plano
• Caso haja redução de valor, será gerado um crédito automaticamente
• Esse crédito poderá ser utilizado na próxima fatura

Dicas importantes

• Revise a quantidade de instâncias antes de confirmar a contratação
• Utilize upgrade para escalar sua operação rapidamente
• Utilize downgrade para otimizar custos quando necessário

Instância de WhatsApp: Como Criar e Gerenciar

Após realizar o cadastro, você recebe um período de teste gratuito de 7 dias, com direito a uma instância de WhatsApp. Esse período permite testar a integração, o envio de mensagens e os recursos de automação disponíveis na plataforma.

O que é uma instância?

Uma instância representa a conexão entre a plataforma e uma conta do WhatsApp.

Por meio da instância, é possível conectar um número de WhatsApp à plataforma e utilizar recursos como:

• Envio e recebimento de mensagens;
• Automação de mensagens;
• Integração com sistemas externos;
• Recebimento de eventos por meio de Webhooks;
• Monitoramento do status das mensagens;
• Integração com grupos e outros eventos do WhatsApp.

OBS.: Para criar uma instância externamente, ou seja, sem utilizar diretamente o painel da plataforma, é necessário utilizar o Token da API disponível no seu perfil.

Como obter o Token da API

Para acessar o Token da API:

1. Acesse o Menu da plataforma.
2. Clique em Meu Perfil.
3. Localize o Token da API.
4. Utilize esse token para autenticar suas requisições.

Importante: mantenha seu Token da API em segurança. Ele funciona como uma credencial de acesso e não deve ser compartilhado publicamente ou exposto em aplicações do lado do cliente.

Endpoint para criação da instância

Para criar uma nova instância utilizando a API, utilize o seguinte endpoint:

POST {{baseUrl}}/:username/:version/instance/add

Estrutura da URL

A URL é composta pelos seguintes parâmetros:

Exemplo de URL:

https://api.uzapi.com.br/teste/v1/instance/add

Configurando a autenticação

A API utiliza o método de autenticação Bearer Token.

Para realizar a requisição pelo Postman, recomendamos criar uma variável de ambiente para armazenar o token.

Variável de ambiente

Nome:

token

Valor:

f23d0183141366265xxxxxx

Depois, acesse a aba Authorization da requisição e configure:

Type: Bearer Token
Token: {{token}}

Dessa forma, o Postman enviará automaticamente o token no cabeçalho da requisição:

Authorization: Bearer SEU_TOKEN

Corpo da requisição

Na aba Body do Postman, selecione:

Body → raw → JSON

Em seguida, informe o seguinte conteúdo:

{
  "name": "Nome da Instância",
  "appVersion": "latest",
  "authenticationMethod": "QRCode",
  "phoneNumber": "Seu número",
  "autoRejectCall": false,
  "answerMissedCall": "Olá, não posso atender ligações.",
  "webhook": "https://webhook.site/receives",
  "webhookEvents": {
    "authentication": true,
    "connection": true,
    "group_messages": true,
    "message_status": true,
    "group_events": true,
    "history": false
  },
  "resources": {
    "resources": {
      "requests": {
        "cpu": "50m",
        "memory": "70Mi"
      },
      "limits": {
        "cpu": "100m",
        "memory": "128Mi"
      }
    }
  }
}

Principais parâmetros

Como criar uma instância pelo Dashboard

Também é possível criar uma instância diretamente pelo painel da plataforma, sem utilizar a API.

Passo a passo

1. Acesse o Dashboard.
2. Clique em Nova Instância.
3. Preencha as informações solicitadas:
   • Nome da instância;
   • Webhook, caso queira receber eventos automaticamente;
   • Método de autenticação.
4. Selecione o método de autenticação desejado:
   • QR Code;
   • Pairing Code, utilizando o número do WhatsApp.
5. Acesse Opções → Autenticação.
6. Caso tenha escolhido QR Code, abra o WhatsApp no celular.
7. Acesse Configurações → Dispositivos conectados.
8. Selecione Conectar dispositivo.
9. Escaneie o QR Code apresentado pela plataforma.
10. Aguarde a conclusão da autenticação e a conexão da instância.

Após a conexão, a instância estará disponível no painel e poderá ser utilizada para realizar a integração com o WhatsApp.

Dica: caso esteja utilizando Webhooks, verifique se a URL configurada está acessível publicamente e preparada para receber as notificações enviadas pela API.

1 Como atualizar uma instância

1. Clique em Opções
2. Selecione Atualizar instância

1.1 Como excluir uma instância

1. Clique em Opções
2. Clique em Deletar instância
3. Confirme em Excluir

1.2 Como reconectar uma instância

Se a conexão cair:

1. Clique em Opções
2. Clique em Desconectar instância
3. Clique em Autenticar
4. Escaneie o QR Code novamente

1.3 Como configurar webhook da instância

O webhook permite integrar eventos com outros sistemas.

1. Clique em Opções
2. Acesse Visualizar instância
3. Vá em Configurações
4. Insira a URL do webhook
5. Clique em Atualizar

1.4 Como visualizar uma instância

1. Clique em Opções
2. Clique em Visualizar instância

Integração da Uzapi com o Chatwoot

Visão geral

A integração da Uzapi com o Chatwoot permite utilizar uma instância do WhatsApp da Uzapi como um canal de atendimento dentro do Chatwoot.

Observação: A integração deve ser configurada inicialmente pela equipe de infraestrutura responsável pelo Chatwoot, pois é necessário alterar uma variável no arquivo .env da aplicação.

A integração é compatível com o Chatwoot a partir da versão 4.10, podendo ser utilizada também em versões posteriores.

1. Configuração do .env do Chatwoot

Primeiramente, acesse o arquivo .env da instalação do Chatwoot.

Localize a variável:

WHATSAPP_CLOUD_BASE_URL=

Configure-a apontando para a URL base da Uzapi, incluindo o username da conta.

Exemplo

WHATSAPP_CLOUD_BASE_URL=https://api.uzapi.com.br/autotic

Importante: Substitua autotic pelo username correspondente à conta Uzapi que será utilizada na integração.

Após realizar a alteração, salve o arquivo .env.

2. Criar uma caixa de entrada do WhatsApp no Chatwoot

Após configurar o .env, acesse o painel do Chatwoot e crie uma nova Caixa de Entrada (Inbox) do tipo WhatsApp.

Preencha os campos solicitados com os dados da conta Uzapi.

Dados da integração

Após preencher todos os campos, clique em Criar Canal.

3. Configurar o Webhook

Após a criação do canal, o Chatwoot irá gerar uma URL de Webhook.

Copiar a URL

Copie a URL de Webhook fornecida pelo Chatwoot.

Em seguida, acesse o painel da Uzapi e navegue até:

Uzapi → Instância → Visualizar Instância → Configuração

Cole a URL do Webhook no campo correspondente e salve a configuração.

4. Desativar eventos de grupo

Atenção: Ao configurar a URL do Webhook do Chatwoot na Uzapi, é necessário desativar os eventos de grupo.

Essa configuração deve ser realizada na instância da Uzapi antes de concluir a integração.

5. Validação da integração

Após concluir todas as etapas:

1. O .env do Chatwoot deve estar configurado com a URL base da Uzapi.
2. A caixa de entrada do tipo WhatsApp deve estar criada no Chatwoot.
3. A URL de Webhook gerada pelo Chatwoot deve estar configurada na instância da Uzapi.
4. Os eventos de grupo devem estar desativados na Uzapi.

Com essas configurações concluídas, a integração entre Uzapi e Chatwoot estará configurada.

6. Vídeo de apoio

Em caso de dúvidas sobre o processo de configuração, consulte o vídeo:

Integrando a API de WhatsApp Uzapi ao Chatwoot

Como criar um novo ticket de suporte

1. No menu lateral, clique em Suporte.
2. Na tela de suporte, clique em Adicionar Novo Ticket.
3. Selecione a categoria correspondente ao seu chamado.
4. Defina a prioridade do atendimento.
5. Preencha as informações necessárias e envie o ticket

Observações

• Todos os registros e interações do atendimento ficam disponíveis no histórico do ticket.
• Novas informações ou respostas da equipe de suporte serão adicionadas diretamente ao chamado.
• Recomenda-se acompanhar periodicamente o ticket para verificar atualizações e responder às solicitações da equipe de suporte, quando necessário.

Acompanhamento de Tickets

Como acompanhar um chamado em andamento

1. No menu lateral, clique em Suporte.
2. Na tela de suporte, localize o ticket que deseja acompanhar.
3. Selecione o ticket desejado.
4. Consulte o histórico de mensagens para acompanhar toda a comunicação e o andamento do atendimento.

Observações

• Todos os registros e interações do atendimento ficam disponíveis no histórico do ticket.
• Novas informações ou respostas da equipe de suporte serão adicionadas diretamente ao chamado.
• Recomenda-se acompanhar periodicamente o ticket para verificar atualizações e responder às solicitações da equipe de suporte, quando necessário.

Testando a API

Acesse o guia de referência da API para explorar e testar todos os endpoints disponíveis.

OBSERVAÇÃO GERAL — Webhook de status das mensagens

O webhook da API não retorna o conteúdo da mensagem enviada, ou seja, o body do webhook não contém o texto enviado como send text.

A API segue o mesmo padrão de funcionamento da API oficial da Meta, mantendo um modelo semelhante de requisição e resposta. Dessa forma, o webhook é utilizado principalmente para informar os eventos e status relacionados à mensagem.

Os principais status retornados pelo webhook são:

• send — mensagem enviada.
• delivery — mensagem entregue.
• read — mensagem lida.

Cada mensagem enviada gera um ID único, que pode ser utilizado para relacionar o evento recebido no webhook à mensagem originalmente enviada.Como o webhook não retorna diretamente o conteúdo da mensagem, caso seja necessário identificar o texto enviado, o sistema deverá implementar uma lógica de relacionamento utilizando o ID da mensagem recebido no webhook. Por exemplo, ao receber automaticamente o status delivery, o sistema poderá utilizar o endpoint getchat, informando o ID recebido no webhook, para localizar o registro correspondente da mensagem enviada. A partir desse registro, será possível identificar o conteúdo da mensagem, bem como outras informações relacionadas ao envio e ao responsável pelo envio.

Documentação da API:
https://api.uzapi.com.br/docs

Swagger:
https://api.uzapi.com.br/swagger

Enviando uma mensagem

Endpoint

POST {{baseUrl}}/:username/:version/:phone_number_id/messages

Obtendo os parâmetros da API

Antes de realizar a requisição, acesse o painel da sua instância e obtenha os seguintes parâmetros:

Configurando a autenticação

A API utiliza autenticação do tipo Bearer Token.

No Postman, crie uma variável de ambiente:

Nome: token

Valor:

eyJhbGcxxxxxx

Em seguida, na aba Authorization da requisição, selecione:

Type: Bearer Token
Token: {{token}}

Testando o endpoint /messages

Corpo da requisição

{
  "to": "55219xxxxxxxx",
  "delayMessage": 0,
  "delayTyping": 0,
  "type": "text",
  "text": {
    "body": "Olá Mundo!"
  }
}

Exemplo de resposta

{
  "status": "success",
  "message": "Mensagem colocada na fila de envios com sucesso!",
  "queueId": "BB3A206B22B97B70E3E2F74197747CB3",
  "messageId": "3EB033430E4C1324B0E016",
  "contacts": [
    {
      "input": "5521xxxxx",
      "wa_id": "5521xxxxx"
    }
  ],
  "messages": [
    {
      "id": "wamid.PXpweDEvZWtnZTZ6Tk1rVFNFOGxZaVIzVnVyT1ZMclhUcHhVdUM9Nw=="
    }
  ]
}

Descrição da resposta

Quando a requisição for processada com sucesso, a mensagem será adicionada à fila de envio e os identificadores retornados poderão ser utilizados para rastreamento e auditoria.

Obtendo o Conteúdo de Mensagens Enviadas

Webhook de status das mensagens

O webhook da API não retorna o conteúdo da mensagem enviada. Ou seja, o corpo (body) recebido no webhook não contém diretamente o texto utilizado no envio da mensagem.

A API segue um modelo de funcionamento semelhante ao da API oficial da Meta, utilizando o webhook principalmente para notificar eventos e alterações de status relacionados às mensagens.

Entre os principais status associados às mensagens estão:

• send — mensagem enviada.
• delivery — mensagem entregue.
• read — mensagem lida.

Importante: o webhook deve ser utilizado para identificar o evento e o status da mensagem. Para obter o conteúdo da mensagem, é necessário consultar posteriormente o registro correspondente utilizando o ID da mensagem.

Cada mensagem enviada possui um ID único. Esse ID permite relacionar o evento recebido pelo webhook com a mensagem originalmente enviada.

Fluxo recomendado

O fluxo para recuperar o conteúdo de uma mensagem enviada pode ser resumido da seguinte forma:

1. A aplicação envia uma mensagem pela API.
2. A API gera um ID exclusivo para a mensagem.
3. Posteriormente, o webhook recebe uma atualização de status relacionada a essa mensagem.
4. O webhook informa o ID da mensagem no campo statuses[].id.
5. A aplicação utiliza esse ID para consultar a mensagem por meio do endpoint de consulta de chats.
6. A resposta da consulta contém as informações da mensagem, incluindo seu conteúdo.

Por exemplo, ao receber um evento com status delivered, o sistema pode utilizar o valor de statuses[].id para consultar a mensagem correspondente.

Dessa forma, não é necessário esperar que o texto da mensagem seja enviado novamente pelo webhook. O conteúdo pode ser recuperado por meio da consulta utilizando o ID da mensagem.

2. Documentação da API

• Documentação da API:
  https://api.uzapi.com.br/docs
• Swagger:
  https://api.uzapi.com.br/swagger

3. Capturando o conteúdo de uma mensagem

Endpoint

POST {{baseUrl}}/:username/:version/:phone_number_id/chats 

4. Obtendo os parâmetros da API

Antes de realizar a requisição, acesse o painel da sua instância e obtenha os parâmetros necessários para montar a URL e autenticar a requisição.

Observação: o message_id utilizado nas consultas deve ser o ID da mensagem retornado pela API ou posteriormente recebido no webhook, conforme o fluxo da integração.

5. Configurando a autenticação

A API utiliza autenticação do tipo Bearer Token.

No Postman, crie uma variável de ambiente chamada token.

Nome:

token

Valor:

eyJhbGcxxxxxx

Na aba Authorization da requisição, configure:

Dessa forma, o Postman enviará automaticamente o token no cabeçalho Authorization:

Authorization: Bearer {{token}}

6. Recebendo o status da mensagem pelo webhook

Após o envio da mensagem, a aplicação poderá receber uma notificação no webhook configurado.

Um exemplo de payload recebido é:

[
  {
    "headers": {
      "connection": "Upgrade",
      "host": "flowtech.autotic.com.br",
      "content-length": "1251",
      "user-agent": "Go-http-client/1.1",
      "content-type": "application/json",
      "accept-encoding": "gzip"
    },
    "params": {},
    "query": {},
    "body": {
      "object": "whatsapp_business_account",
      "entry": [
        {
          "id": "",
          "changes": [
            {
              "value": {
                "messaging_product": "whatsapp",
                "metadata": {
                  "display_phone_number": "5521979844840",
                  "phone_number_id": "755574361041503"
                },
                "contacts": [
                  {
                    "profile": {
                      "name": ""
                    },
                    "wa_id": "5521993432153"
                  }
                ],
                "statuses": [
                  {
                    "id": "ACB96BCE62812FBD9E2983DA5586E4B6",
                    "status": "delivered",
                    "timestamp": "1787758728",
                    "recipient_id": "",
                    "conversation": {
                      "id": "wamid.DAYwsim1GxznkgJevwqFIRGAto8fP+MbdNIunJr4qhentGt0gERI8b0MdqgjgAg6fj2IettSLvXnQpJh",
                      "origin": {
                        "type": "service"
                      }
                    },
                    "pricing": {
                      "billable": true,
                      "pricing_model": "CBP",
                      "category": "service"
                    }
                  }
                ]
              },
              "field": "messages"
            }
          ]
        }
      ]
    },
    "webhookUrl": "https://flowtech.autotic.com.br/webhook/uzapi",
    "executionMode": "production"
  }
]

Identificando a mensagem

No exemplo acima, o campo:

"statuses": [
  {
    "id": "ACB96BCE62812FBD9E2983DA5586E4B6",
    "status": "delivered"
  }
]

indica que a mensagem possui o ID:

ACB96BCE62812FBD9E2983DA5586E4B6

Esse valor deve ser utilizado para localizar a mensagem correspondente.

O campo status informa o estado atual da mensagem. No exemplo, o valor:

delivered

indica que a mensagem foi entregue.

Importante: o payload do webhook apresentado acima não contém o campo com o texto da mensagem. Para obter esse conteúdo, utilize o ID informado em statuses[].id e faça uma consulta à API.

7. Consultando a mensagem pelo ID

Depois de obter o ID da mensagem no webhook, é possível consultar o registro correspondente utilizando a operação get.

Requisição

{
  "delayMessage": 0,
  "type": "chats",
  "action": "get",
  "chats": {
    "message_id": "ACB96BCE62812FBD9E2983DA5586E4B6"
  }
}

Atenção: utilize no campo message_id o mesmo ID recebido no webhook em statuses[].id.

8. Exemplo de resposta

Uma resposta possível para a consulta é:

[
  {
    "status": "success",
    "data": {
      "data": {
        "Info": {
          "Chat": "152943902851129@lid",
          "Sender": "35682672189672@lid",
          "IsFromMe": true,
          "IsGroup": false,
          "ID": "ACB96BCE62812FBD9E2983DA5586E4B6",
          "Type": "text",
          "PushName": "T",
          "Timestamp": "2026-08-26T15:38:48Z"
        },
        "Message": {
          "Conversation": "Testando novamente",
          "MessageContextInfo": {
            "deviceListMetadata": {
              "senderKeyHash": "5yR/b2vqtw7V8w==",
              "senderTimestamp": 1787755863,
              "recipientKeyHash": "0Rge/zZZCTCdrg==",
              "recipientTimestamp": 1787276551
            },
            "deviceListMetadataVersion": 2,
            "messageSecret": "jtSscSMZNIOYPYuPduLYSKCfslxpJpRRgNMRBceo0Lc="
          }
        }
      },
      "status": "success"
    }
  }
]

9. Localizando o conteúdo da mensagem

Na resposta acima, o conteúdo da mensagem está disponível em:

data.data.Message.Conversation

No exemplo:

"Message": {
  "Conversation": "Testando novamente"
}

Portanto, o conteúdo enviado foi:

Testando novamente

O ID da mensagem pode ser conferido no campo:

data.data.Info.ID

que, no exemplo, corresponde a:

ACB96BCE62812FBD9E2983DA5586E4B6

10. Resumo do processo

A integração pode ser implementada seguindo este fluxo:

ENVIO DA MENSAGEM
       │
       ▼
API gera/retorna o ID da mensagem
       │
       ▼
Webhook recebe atualização de status
       │
       ▼
statuses[].id
       │
       ▼
Consulta da mensagem utilizando message_id
       │
       ▼
Resposta da API
       │
       ▼
Message.Conversation
       │
       ▼
Conteúdo da mensagem

Exemplo prático

Se o webhook receber:

{
  "id": "ACB96BCE62812FBD9E2983DA5586E4B6",
  "status": "delivered"
}

a aplicação deverá utilizar o ID:

ACB96BCE62812FBD9E2983DA5586E4B6

na consulta:

{
  "delayMessage": 0,
  "type": "chats",
  "action": "get",
  "chats": {
    "message_id": "ACB96BCE62812FBD9E2983DA5586E4B6"
  }
}

A partir da resposta, o sistema poderá acessar:

Message.Conversation
para obter o texto da mensagem.

11. Conclusão

O webhook de status não deve ser utilizado como fonte do conteúdo da mensagem enviada. Sua principal finalidade é informar eventos e alterações de status.

Para identificar o conteúdo de uma mensagem enviada, o sistema deve:

1. Capturar o ID da mensagem.
2. Identificar o ID correspondente no webhook por meio de statuses[].id.
3. Consultar a mensagem utilizando message_id.
4. Obter o conteúdo no campo Message.Conversation.