Invio dei messaggi

Tutti i messaggi vengono inviati attraverso un unico endpoint. Il campo type determina il tipo di messaggio inviato e i campi rimanenti variano di conseguenza. Endpoint:

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

Header:

Header	Valore
`X-Api-Key`	La tua chiave API
`Content-Type`	`application/json`

Messaggio di testo

Invia un messaggio di testo semplice.

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);

Risposta:

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

Messaggio con immagine

Invia un’immagine con una didascalia opzionale.

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!",
    }),
  }
);

Messaggio video

Invia un file video con una didascalia opzionale.

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!",
    }),
  }
);

Messaggio audio

Invia un file audio. I messaggi audio vengono visualizzati come messaggi vocali in 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",
    }),
  }
);

Per la massima compatibilita, utilizza file .ogg codificati con il codec Opus per i messaggi vocali.

Messaggio documento

Invia un file come allegato 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",
    }),
  }
);

Messaggio di posizione

Invia un segnaposto di posizione 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",
    }),
  }
);

Messaggio sondaggio

Crea un sondaggio interattivo. I destinatari possono votare le opzioni direttamente in 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,
    }),
  }
);

Messaggio contatto / vCard

Condividi una scheda contatto.

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",
    }),
  }
);

Inoltrare un messaggio

Inoltra un messaggio esistente a un’altra 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",
    }),
  }
);

Reazione

Reagisci a un messaggio 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",
    }),
  }
);

Per rimuovere una reazione, invia una stringa vuota come valore di reaction.

Funzionalita avanzate

Rispondere a un messaggio

Cita un messaggio precedente includendo quoted_message_id. Funziona con qualsiasi tipo di messaggio.

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",
    }),
  }
);

Modificare un messaggio inviato

Modifica un messaggio inviato in precedenza fornendo 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",
    }),
  }
);

Puoi modificare solo i messaggi che hai inviato tu. La modifica ha un limite temporale imposto da WhatsApp (circa 15 minuti dopo l’invio).

Menzioni

Menziona contatti specifici in un messaggio di gruppo. I contatti menzionati riceveranno una notifica.

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",
      ],
    }),
  }
);

Formati degli ID chat

Formato	Descrizione	Esempio
`{phone}@s.whatsapp.net`	Chat individuale	`5511999998888@s.whatsapp.net`
`{id}@g.us`	Chat di gruppo	`120363012345678901@g.us`

Numeri di telefono brasiliani

Wappfy gestisce automaticamente il problema della nona cifra brasiliana. Se un messaggio fallisce con un errore “no LID found”, il sistema riprova automaticamente con il formato alternativo (aggiungendo o rimuovendo la nona cifra).Ad esempio, se 5511999998888 fallisce, riprova con 551199998888, e viceversa. Questo avviene in modo trasparente — non devi gestirlo manualmente.

Riferimento dei tipi di messaggio

Tipo	Campi obbligatori	Campi opzionali
`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`	—

Gestione degli errori

Codice di stato	Descrizione
`400`	Payload del messaggio non valido (es. campi obbligatori mancanti per il tipo specificato).
`404`	Istanza non trovata o non connessa.
`422`	Validazione del messaggio fallita (es. formato del numero di telefono non valido).
`429`	Limite di frequenza superato. Consulta Limiti di frequenza.
`502`	Il provider WhatsApp ha restituito un errore. Controlla il messaggio di errore per i dettagli.

Per Iniziare

Guide

Invio dei messaggi

Invio dei messaggi

Messaggio di testo

Messaggio con immagine

Messaggio video

Messaggio audio

Messaggio documento

Messaggio di posizione

Messaggio sondaggio

Messaggio contatto / vCard

Inoltrare un messaggio

Reazione

Funzionalita avanzate

Rispondere a un messaggio

Modificare un messaggio inviato

Menzioni

Formati degli ID chat

Numeri di telefono brasiliani

Riferimento dei tipi di messaggio

Gestione degli errori

​Invio dei messaggi

​Messaggio di testo

​Messaggio con immagine

​Messaggio video

​Messaggio audio

​Messaggio documento

​Messaggio di posizione

​Messaggio sondaggio

​Messaggio contatto / vCard

​Inoltrare un messaggio

​Reazione

​Funzionalita avanzate

​Rispondere a un messaggio

​Modificare un messaggio inviato

​Menzioni

​Formati degli ID chat

​Numeri di telefono brasiliani

​Riferimento dei tipi di messaggio

​Gestione degli errori

Invio dei messaggi

Messaggio di testo

Messaggio con immagine

Messaggio video

Messaggio audio

Messaggio documento

Messaggio di posizione

Messaggio sondaggio

Messaggio contatto / vCard

Inoltrare un messaggio

Reazione

Funzionalita avanzate

Rispondere a un messaggio

Modificare un messaggio inviato

Menzioni

Formati degli ID chat

Numeri di telefono brasiliani

Riferimento dei tipi di messaggio

Gestione degli errori