Envio de mensajes

Todos los mensajes se envian a traves de un unico endpoint. El campo type determina que tipo de mensaje se envia, y los demas campos cambian en consecuencia. Endpoint:

POST https://api.wappfy.io/api/instances/{instanceId}/messages/send

Headers:

Header	Valor
`X-Api-Key`	Tu clave API
`Content-Type`	`application/json`

Mensaje de texto

Envia un mensaje de texto plano.

curl -X POST https://api.wappfy.io/api/instances/inst_abc123/messages/send \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "5511999998888@s.whatsapp.net",
    "type": "text",
    "text": "Hello from Wappfy!"
  }'

const response = await fetch(
  "https://api.wappfy.io/api/instances/inst_abc123/messages/send",
  {
    method: "POST",
    headers: {
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      chat_id: "5511999998888@s.whatsapp.net",
      type: "text",
      text: "Hello from Wappfy!",
    }),
  }
);

const result = await response.json();
console.log(result.data.message_id);

Respuesta:

{
  "data": {
    "message_id": "BAE5F2C4D3B2A1",
    "status": "sent"
  }
}

Mensaje de imagen

Envia una imagen con una descripcion opcional.

curl -X POST https://api.wappfy.io/api/instances/inst_abc123/messages/send \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "5511999998888@s.whatsapp.net",
    "type": "image",
    "media_url": "https://example.com/photo.jpg",
    "caption": "Check out this photo!"
  }'

await fetch(
  "https://api.wappfy.io/api/instances/inst_abc123/messages/send",
  {
    method: "POST",
    headers: {
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      chat_id: "5511999998888@s.whatsapp.net",
      type: "image",
      media_url: "https://example.com/photo.jpg",
      caption: "Check out this photo!",
    }),
  }
);

Mensaje de video

Envia un archivo de video con una descripcion opcional.

curl -X POST https://api.wappfy.io/api/instances/inst_abc123/messages/send \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "5511999998888@s.whatsapp.net",
    "type": "video",
    "media_url": "https://example.com/clip.mp4",
    "caption": "Watch this!"
  }'

await fetch(
  "https://api.wappfy.io/api/instances/inst_abc123/messages/send",
  {
    method: "POST",
    headers: {
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      chat_id: "5511999998888@s.whatsapp.net",
      type: "video",
      media_url: "https://example.com/clip.mp4",
      caption: "Watch this!",
    }),
  }
);

Mensaje de audio

Envia un archivo de audio. Los mensajes de audio aparecen como mensajes de voz en WhatsApp.

curl -X POST https://api.wappfy.io/api/instances/inst_abc123/messages/send \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "5511999998888@s.whatsapp.net",
    "type": "audio",
    "media_url": "https://example.com/voice-note.ogg"
  }'

await fetch(
  "https://api.wappfy.io/api/instances/inst_abc123/messages/send",
  {
    method: "POST",
    headers: {
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      chat_id: "5511999998888@s.whatsapp.net",
      type: "audio",
      media_url: "https://example.com/voice-note.ogg",
    }),
  }
);

Para mejor compatibilidad, usa archivos .ogg codificados con el codec Opus para mensajes de voz.

Mensaje de documento

Envia un archivo como adjunto de documento.

curl -X POST https://api.wappfy.io/api/instances/inst_abc123/messages/send \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "5511999998888@s.whatsapp.net",
    "type": "document",
    "media_url": "https://example.com/report.pdf",
    "filename": "Q1-Report.pdf",
    "caption": "Here is the quarterly report"
  }'

await fetch(
  "https://api.wappfy.io/api/instances/inst_abc123/messages/send",
  {
    method: "POST",
    headers: {
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      chat_id: "5511999998888@s.whatsapp.net",
      type: "document",
      media_url: "https://example.com/report.pdf",
      filename: "Q1-Report.pdf",
      caption: "Here is the quarterly report",
    }),
  }
);

Mensaje de ubicacion

Envia un pin de ubicacion geografica.

curl -X POST https://api.wappfy.io/api/instances/inst_abc123/messages/send \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "5511999998888@s.whatsapp.net",
    "type": "location",
    "latitude": -23.5505,
    "longitude": -46.6333,
    "name": "Sao Paulo",
    "address": "Sao Paulo, SP, Brazil"
  }'

await fetch(
  "https://api.wappfy.io/api/instances/inst_abc123/messages/send",
  {
    method: "POST",
    headers: {
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      chat_id: "5511999998888@s.whatsapp.net",
      type: "location",
      latitude: -23.5505,
      longitude: -46.6333,
      name: "Sao Paulo",
      address: "Sao Paulo, SP, Brazil",
    }),
  }
);

Mensaje de encuesta

Crea una encuesta interactiva. Los destinatarios pueden votar las opciones directamente en WhatsApp.

curl -X POST https://api.wappfy.io/api/instances/inst_abc123/messages/send \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "5511999998888@s.whatsapp.net",
    "type": "poll",
    "poll_name": "What day works best for the meeting?",
    "poll_options": ["Monday", "Wednesday", "Friday"],
    "poll_allow_multiple": false
  }'

await fetch(
  "https://api.wappfy.io/api/instances/inst_abc123/messages/send",
  {
    method: "POST",
    headers: {
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      chat_id: "5511999998888@s.whatsapp.net",
      type: "poll",
      poll_name: "What day works best for the meeting?",
      poll_options: ["Monday", "Wednesday", "Friday"],
      poll_allow_multiple: false,
    }),
  }
);

Mensaje de contacto / vCard

Comparte una tarjeta de contacto.

curl -X POST https://api.wappfy.io/api/instances/inst_abc123/messages/send \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "5511999998888@s.whatsapp.net",
    "type": "contact",
    "contact_name": "Maria Silva",
    "contact_phone": "+5511988887777"
  }'

await fetch(
  "https://api.wappfy.io/api/instances/inst_abc123/messages/send",
  {
    method: "POST",
    headers: {
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      chat_id: "5511999998888@s.whatsapp.net",
      type: "contact",
      contact_name: "Maria Silva",
      contact_phone: "+5511988887777",
    }),
  }
);

Reenviar mensaje

Reenvia un mensaje existente a otro chat.

curl -X POST https://api.wappfy.io/api/instances/inst_abc123/messages/send \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "5511888887777@s.whatsapp.net",
    "type": "forward",
    "forward_message_id": "BAE5F2C4D3B2A1",
    "forward_chat_id": "5511999998888@s.whatsapp.net"
  }'

await fetch(
  "https://api.wappfy.io/api/instances/inst_abc123/messages/send",
  {
    method: "POST",
    headers: {
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      chat_id: "5511888887777@s.whatsapp.net",
      type: "forward",
      forward_message_id: "BAE5F2C4D3B2A1",
      forward_chat_id: "5511999998888@s.whatsapp.net",
    }),
  }
);

Reaccion

Reacciona a un mensaje con un emoji.

curl -X POST https://api.wappfy.io/api/instances/inst_abc123/messages/send \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "5511999998888@s.whatsapp.net",
    "type": "reaction",
    "reaction_message_id": "BAE5F2C4D3B2A1",
    "reaction": "\ud83d\udc4d"
  }'

await fetch(
  "https://api.wappfy.io/api/instances/inst_abc123/messages/send",
  {
    method: "POST",
    headers: {
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      chat_id: "5511999998888@s.whatsapp.net",
      type: "reaction",
      reaction_message_id: "BAE5F2C4D3B2A1",
      reaction: "\ud83d\udc4d",
    }),
  }
);

Para eliminar una reaccion, envia una cadena vacia como valor de reaction.

Funcionalidades avanzadas

Responder a un mensaje

Cita un mensaje anterior incluyendo quoted_message_id. Esto funciona con cualquier tipo de mensaje.

curl -X POST https://api.wappfy.io/api/instances/inst_abc123/messages/send \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "5511999998888@s.whatsapp.net",
    "type": "text",
    "text": "Yes, I agree with this!",
    "quoted_message_id": "BAE5F2C4D3B2A1"
  }'

await fetch(
  "https://api.wappfy.io/api/instances/inst_abc123/messages/send",
  {
    method: "POST",
    headers: {
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      chat_id: "5511999998888@s.whatsapp.net",
      type: "text",
      text: "Yes, I agree with this!",
      quoted_message_id: "BAE5F2C4D3B2A1",
    }),
  }
);

Editar un mensaje enviado

Edita un mensaje que enviaste previamente proporcionando edit_message_id.

curl -X POST https://api.wappfy.io/api/instances/inst_abc123/messages/send \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "5511999998888@s.whatsapp.net",
    "type": "text",
    "text": "Updated message content",
    "edit_message_id": "BAE5F2C4D3B2A1"
  }'

await fetch(
  "https://api.wappfy.io/api/instances/inst_abc123/messages/send",
  {
    method: "POST",
    headers: {
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      chat_id: "5511999998888@s.whatsapp.net",
      type: "text",
      text: "Updated message content",
      edit_message_id: "BAE5F2C4D3B2A1",
    }),
  }
);

Solo puedes editar mensajes que tu enviaste. La edicion tiene una ventana de tiempo limitada impuesta por WhatsApp (aproximadamente 15 minutos despues del envio).

Menciones

Menciona contactos especificos en un mensaje de grupo. Los contactos mencionados recibiran una notificacion.

curl -X POST https://api.wappfy.io/api/instances/inst_abc123/messages/send \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "120363012345678901@g.us",
    "type": "text",
    "text": "Hey @Maria and @Carlos, please review this.",
    "mentions": [
      "5511999998888@s.whatsapp.net",
      "5511888887777@s.whatsapp.net"
    ]
  }'

await fetch(
  "https://api.wappfy.io/api/instances/inst_abc123/messages/send",
  {
    method: "POST",
    headers: {
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      chat_id: "120363012345678901@g.us",
      type: "text",
      text: "Hey @Maria and @Carlos, please review this.",
      mentions: [
        "5511999998888@s.whatsapp.net",
        "5511888887777@s.whatsapp.net",
      ],
    }),
  }
);

Formatos de Chat ID

Formato	Descripcion	Ejemplo
`{phone}@s.whatsapp.net`	Chat individual	`5511999998888@s.whatsapp.net`
`{id}@g.us`	Chat grupal	`120363012345678901@g.us`

Numeros de telefono brasilenhos

Wappfy maneja automaticamente el problema del 9no digito brasilenho. Si un mensaje falla con un error “no LID found”, el sistema reintentara automaticamente con el formato alternativo (agregando o quitando el 9no digito).Por ejemplo, si 5511999998888 falla, se reintentara con 551199998888, y viceversa. Esto ocurre de forma transparente — no necesitas manejarlo tu mismo.

Referencia de tipos de mensaje

Tipo	Campos obligatorios	Campos opcionales
`text`	`text`	`quoted_message_id`, `edit_message_id`, `mentions`
`image`	`media_url`	`caption`, `quoted_message_id`
`video`	`media_url`	`caption`, `quoted_message_id`
`audio`	`media_url`	`quoted_message_id`
`document`	`media_url`	`filename`, `caption`, `quoted_message_id`
`location`	`latitude`, `longitude`	`name`, `address`, `quoted_message_id`
`poll`	`poll_name`, `poll_options`	`poll_allow_multiple`
`contact`	`contact_name`, `contact_phone`	`quoted_message_id`
`forward`	`forward_message_id`, `forward_chat_id`	—
`reaction`	`reaction_message_id`, `reaction`	—

Manejo de errores

Codigo de estado	Descripcion
`400`	Payload de mensaje invalido (por ejemplo, faltan campos obligatorios para el tipo dado).
`404`	Instancia no encontrada o no conectada.
`422`	La validacion del mensaje fallo (por ejemplo, formato de numero de telefono invalido).
`429`	Limite de tasa excedido. Consulta Limites de tasa.
`502`	El proveedor de WhatsApp devolvio un error. Revisa el mensaje de error para mas detalles.

Primeros Pasos

Guías

Envio de mensajes

Envio de mensajes

Mensaje de texto

Mensaje de imagen

Mensaje de video

Mensaje de audio

Mensaje de documento

Mensaje de ubicacion

Mensaje de encuesta

Mensaje de contacto / vCard

Reenviar mensaje

Reaccion

Funcionalidades avanzadas

Responder a un mensaje

Editar un mensaje enviado

Menciones

Formatos de Chat ID

Numeros de telefono brasilenhos

Referencia de tipos de mensaje

Manejo de errores

​Envio de mensajes

​Mensaje de texto

​Mensaje de imagen

​Mensaje de video

​Mensaje de audio

​Mensaje de documento

​Mensaje de ubicacion

​Mensaje de encuesta

​Mensaje de contacto / vCard

​Reenviar mensaje

​Reaccion

​Funcionalidades avanzadas

​Responder a un mensaje

​Editar un mensaje enviado

​Menciones

​Formatos de Chat ID

​Numeros de telefono brasilenhos

​Referencia de tipos de mensaje

​Manejo de errores

Envio de mensajes

Mensaje de texto

Mensaje de imagen

Mensaje de video

Mensaje de audio

Mensaje de documento

Mensaje de ubicacion

Mensaje de encuesta

Mensaje de contacto / vCard

Reenviar mensaje

Reaccion

Funcionalidades avanzadas

Responder a un mensaje

Editar un mensaje enviado

Menciones

Formatos de Chat ID

Numeros de telefono brasilenhos

Referencia de tipos de mensaje

Manejo de errores