ZapYou - Plataforma de WhatsApp Business

Introdução

Bem-vindo à API do ZapYou

A API do ZapYou permite que você integre o poder do WhatsApp Business em suas aplicações. Envie mensagens, gerencie instâncias, consulte históricos e muito mais, tudo através de uma API RESTful simples e poderosa.

15 Endpoints

Cobertura completa de funcionalidades

4 Webhooks

Receba eventos em tempo real

RESTful

Padrões modernos e consistentes

URL Base

https://api.zapyou.com/v1/api/

Formato de Resposta

Todas as respostas da API são retornadas em formato JSON:

{
  "success": true,
  "data": { ... }
}

Autenticação

A API do ZapYou utiliza dois tipos de autenticação diferentes dependendo do tipo de operação que você deseja realizar.

Company Member Token

Gerenciamento

Usado para operações de gerenciamento como:

Listar instâncias
Ligar/desligar instâncias
Consultar mensagens
Configurar webhooks

Onde obter:

Configurações → API → Company Member Token

Instance Token

Envio de Mensagens

Usado para envio de mensagens. Cada instância tem seu próprio token:

Enviar texto
Enviar imagem
Enviar vídeo/áudio
Enviar documento

Onde obter:

Instâncias → [Instância] → Token

Como Usar

Inclua o token no header Authorization de todas as suas requisições:

Authorization: Bearer YOUR_TOKEN_HERE

Referência da API

Explore todos os endpoints disponíveis na API do ZapYou, organizados por categoria.

Gerenciamento de Instâncias

Autenticação: Estes endpoints requerem um Company Member Token

GET/instances

Listar Instâncias

Retorna a lista de todas as instâncias do WhatsApp da empresa.

Envio de Mensagens

Autenticação: Estes endpoints requerem um Instance Token

POST/instances/send/text/:instanceId

Enviar Mensagem de Texto

Envia uma mensagem de texto para um contato do WhatsApp.

POST/instances/send/image/:instanceId

Enviar Imagem

Envia uma imagem com legenda opcional para um contato do WhatsApp.

POST/instances/send/video/:instanceId

Enviar Vídeo

Envia um vídeo para um contato do WhatsApp.

POST/instances/send/audio/:instanceId

Enviar Áudio

Envia um áudio ou nota de voz (PTT) para um contato do WhatsApp.

POST/instances/send/document/:instanceId

Enviar Documento

Envia um documento (PDF, DOC, etc) para um contato do WhatsApp.

Consulta de Mensagens

Autenticação: Estes endpoints requerem um Company Member Token

GET/messages

Listar Mensagens

Retorna a lista de mensagens com paginação por cursor.

GET/messages/:phone

Buscar Mensagens por Telefone

Retorna todas as mensagens trocadas com um número específico.

POST/messages/clear-cache

Limpar Cache de Mensagens

Limpa o cache de mensagens da empresa.

Campanhas

Autenticação: Este endpoint requer um Company Member Token

GET/campaigns

Listar Campanhas Recentes

Retorna as campanhas dos últimos 3 dias.

Webhooks

O que são Webhooks?

Webhooks são notificações HTTP POST enviadas automaticamente para URLs configuradas quando eventos específicos ocorrem no ZapYou. Use webhooks para receber atualizações em tempo real sobre mensagens, status e conexões.

Configuração

Configure as URLs usando o endpoint PUT /instances/webhooks/:instanceId

Formato

Todas as requisições são POST com Content-Type: application/json

messageURL

Disparado quando uma nova mensagem é recebida ou enviada. Este é o webhook de maior frequência, sendo chamado para cada mensagem trocada.

Payload Fields

Field	Type	Description
`event`	string	Nome do evento (message)
`datetime`	string	Data e hora do evento em formato ISO
`payload.instance`	string	UUID da instância
`payload.code`	string	Código da instância
`payload.message`	string	ID único da mensagem
`payload.type`	string	Tipo da mensagem (text, image, audio, video, document)
`payload.fromMe`	boolean	Se a mensagem foi enviada por você
`payload.remotePhone`	string	Número do contato remoto
`payload.connectedPhone`	string	Número da instância conectada
`payload.text`	string	Conteúdo da mensagem de texto
`payload.file`	object	Informações do arquivo (para mídia)
`payload.group`	object	Informações do grupo (se for mensagem de grupo)
`payload.quoted`	object	Informações da mensagem citada (se for resposta)
`payload.status`	string	Status da mensagem (received, sent)
`payload.pushName`	string	Nome do contato no WhatsApp
`payload.createdAt`	string	Data de criação da mensagem

Example Payload

JSON

{
  "event": "message",
  "datetime": "2026-01-08T14:30:45.000Z",
  "payload": {
    "instance": "507f1f77bcf86cd799439011",
    "code": "INST-001",
    "message": "3EB0F7C8E2D4A3B1",
    "type": "text",
    "fromMe": false,
    "remotePhone": "5511999887766",
    "connectedPhone": "5511888776655",
    "text": "Olá, gostaria de informações sobre produtos",
    "file": {
      "is": false,
      "url": null,
      "mimetype": null,
      "filename": null,
      "size": null
    },
    "group": {
      "is": false,
      "id": null
    },
    "forwarded": {
      "is": false
    },
    "quoted": {
      "is": false,
      "messageId": null,
      "text": null,
      "fromMe": null,
      "remotePhone": null
    },
    "mentions": [],
    "contacts": [],
    "localization": {
      "is": false,
      "latitude": null,
      "longitude": null
    },
    "status": "received",
    "pushName": "João Silva",
    "createdAt": "2026-01-08T14:30:45.000Z",
    "registryType": "text"
  }
}

statusMessageURL

Disparado quando o status de uma mensagem muda. Cada mensagem enviada gera de 3 a 4 chamadas: sent, delivered, read (e opcionalmente failed).

Payload Fields

Field	Type	Description
`event`	string	Nome do evento (ack)
`datetime`	string	Data e hora do evento em formato ISO
`payload.instance`	string	UUID da instância
`payload.code`	string	Código da instância
`payload.message`	string	ID da mensagem
`payload.status`	string	Status: sent, delivered, read, failed

Example Payload

JSON

{
  "event": "ack",
  "datetime": "2026-01-08T14:31:00.000Z",
  "payload": {
    "instance": "507f1f77bcf86cd799439011",
    "code": "INST-001",
    "message": "3EB0F7C8E2D4A3B1",
    "status": "read"
  }
}

connectedURL

Disparado quando uma instância se conecta com sucesso ao WhatsApp. Este é um evento de baixa frequência.

Payload Fields

Field	Type	Description
`event`	string	Nome do evento (connected)
`datetime`	string	Data e hora do evento em formato ISO
`payload.instance`	string	UUID da instância
`payload.code`	string	Código da instância
`payload.connectedPhone`	string	Número do WhatsApp conectado

Example Payload

JSON

{
  "event": "connected",
  "datetime": "2026-01-08T14:30:00.000Z",
  "payload": {
    "instance": "507f1f77bcf86cd799439011",
    "code": "INST-001",
    "connectedPhone": "5511888776655"
  }
}

disconnectedURL

Disparado quando uma instância é desconectada do WhatsApp (logout, sessão expirada, etc). Este é um evento de baixa frequência.

Payload Fields

Field	Type	Description
`event`	string	Nome do evento (disconnected)
`datetime`	string	Data e hora do evento em formato ISO
`payload.instance`	string	UUID da instância
`payload.code`	string	Código da instância
`payload.reason`	string	Motivo da desconexão

Example Payload

JSON

{
  "event": "disconnected",
  "datetime": "2026-01-08T15:00:00.000Z",
  "payload": {
    "instance": "507f1f77bcf86cd799439011",
    "code": "INST-001",
    "reason": "logout"
  }
}

Códigos de Erro

A API do ZapYou usa códigos de status HTTP convencionais para indicar sucesso ou falha de uma requisição. Códigos na faixa 2xx indicam sucesso, códigos na faixa 4xx indicam erro do cliente, e códigos na faixa 5xx indicam erro do servidor.

Code	Status	Name	Description	Solution
`SUCCESS`	200	Sucesso	Requisição processada com sucesso	Nenhuma ação necessária
`BAD_REQUEST`	400	Requisição Inválida	Erro de validação nos dados enviados	Verifique os parâmetros e formato dos dados enviados
`UNAUTHORIZED`	401	Não Autorizado	Token de autenticação inválido ou ausente	Verifique se o token está correto e não expirou
`PAYMENT_REQUIRED`	402	Pagamento Necessário	Saldo insuficiente para enviar mensagens	Recarregue seu saldo na plataforma ZapYou
`FORBIDDEN`	403	Acesso Negado	Você não tem permissão para acessar este recurso	Verifique se seu token tem as permissões necessárias
`NOT_FOUND`	404	Não Encontrado	Recurso solicitado não foi encontrado	Verifique se o ID ou endpoint estão corretos
`RATE_LIMIT_EXCEEDED`	429	Limite de Taxa Excedido	Muitas requisições em um curto período	Aguarde alguns segundos antes de fazer novas requisições
`INTERNAL_ERROR`	500	Erro Interno do Servidor	Erro inesperado no servidor	Tente novamente mais tarde ou contate o suporte
`SERVICE_UNAVAILABLE`	503	Serviço Indisponível	Serviço temporariamente indisponível	Aguarde alguns minutos e tente novamente

Limites de Taxa

Limites de Requisição

Para garantir a qualidade do serviço para todos os usuários, a API do ZapYou implementa limites de taxa nas requisições. Se você exceder o limite, receberá um erro 429 Too Many Requests.

Dica: Implemente um sistema de retry com backoff exponencial para lidar com erros 429 de forma elegante.

POST /instances/send/*

Máximo de 30 mensagens por minuto por instanceId

Requisições

por minuto

GET /instances

Máximo de 100 requisições por minuto por token

100

Requisições

por minuto

GET /messages

Máximo de 100 requisições por minuto por token

100

Requisições

por minuto

GET /campaigns

Máximo de 100 requisições por minuto por token

100

Requisições

por minuto

ZapYou APIDocumentação

Introdução

Bem-vindo à API do ZapYou

URL Base

Formato de Resposta

Autenticação

Company Member Token

Instance Token

Como Usar

Referência da API

Gerenciamento de Instâncias

Listar Instâncias

Envio de Mensagens

Enviar Mensagem de Texto

Enviar Imagem

Enviar Vídeo

Enviar Áudio

Enviar Documento

Consulta de Mensagens

Listar Mensagens

Buscar Mensagens por Telefone

Limpar Cache de Mensagens

Campanhas

Listar Campanhas Recentes

Webhooks

O que são Webhooks?

Payload Fields

Example Payload

Payload Fields

Example Payload

Payload Fields

Example Payload

Payload Fields

Example Payload

Códigos de Erro

Limites de Taxa

Limites de Requisição

ZapYou API
Documentação