WhatSMS/API Docs
Swagger →Inizia gratis
IntroduzioneAutenticazioneErroriTicket↳ MessaggiContattiCampagneAgenti IAWebhooksLimiti di velocitàSDK e n8n
⚡ Swagger interattivo

Introduzione

L'API REST di WhatSMS consente di inviare messaggi, gestire contatti, ticket e campagne e di ascoltare eventi in tempo reale tramite webhook. Ogni richiesta è autenticata tramite API Key e isolata per tenant.

v2

URL di base

https://api.whatsms.pt/api/v2

CRUD completo, paginazione strutturata, supporto media e rate limiting per API Key.

🔑

API Key per tenant

Ogni account ha la propria API Key. Crea e revoca in Impostazioni → Integrazioni → API Keys.

🔒

HTTPS obbligatorio

Tutte le richieste devono usare HTTPS. Le richieste HTTP vengono rifiutate automaticamente.

🇪🇺

GDPR nativo

I dati restano su server europei. Conformità GDPR nativa, senza inviare dati al di fuori dell'UE.

Autenticazione

Ogni richiesta richiede l'header Authorization con l'API Key in formato Bearer. Ottieni la tua API Key in Impostazioni → Integrazioni → API Keys.

Header obbligatorio

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Esempio cURL

curl -X GET https://api.whatsms.pt/api/v2/contacts \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json"

⚠️ Sicurezza

Non esporre mai l'API Key in codice lato client o repository pubblici. Usa variabili d'ambiente sul server. Se una key viene compromessa, revocala immediatamente in Impostazioni → Integrazioni → API Keys.

Errori

L'API usa codici HTTP standard. Il corpo dell'errore segue sempre questa struttura:

Formato dell'errore

{ "error": "Mensagem descritiva do erro" }
CodiceSignificato
200Successo
201Creato con successo
400Richiesta non valida — parametri mancanti o errati
401Non autenticato — API Key non valida o mancante
403Nessun permesso per questa risorsa
404Risorsa non trovata
429Limite di frequenza raggiunto — attendi prima di riprovare
500Errore interno del server

Ticket

Un ticket rappresenta una conversazione con un contatto. Raggruppa messaggi, canale, stato e l'agente responsabile.

GET/api/v2/ticketsElenca ticket

Parametri

status·string

Filtra per stato: open, pending, closed

contactId·uuid

Filtra per contatto

pageNumber·integer

Pagina (default: 1)

pageSize·integer

Risultati per pagina (default: 20, max: 100)

Risposta

{
  "tickets": [
    {
      "id": "uuid",
      "status": "open",
      "channel": "whatsapp",
      "contact": { "id": "uuid", "name": "João Silva", "number": "351910000000" },
      "lastMessage": "Olá, preciso de ajuda",
      "createdAt": "2026-01-15T10:30:00Z"
    }
  ],
  "count": 42,
  "hasMore": true
}
GET/api/v2/tickets/:ticketIdOttieni ticket per ID

Parametri

ticketId·uuidobbligatorio

ID del ticket

Risposta

{
  "ticket": {
    "id": "uuid",
    "status": "open",
    "channel": "whatsapp",
    "contact": { "id": "uuid", "name": "João Silva", "number": "351910000000" },
    "user": { "id": "uuid", "name": "Agente" },
    "queue": { "id": "uuid", "name": "Suporte" },
    "createdAt": "2026-01-15T10:30:00Z",
    "updatedAt": "2026-01-15T11:00:00Z"
  }
}
POST/api/v2/ticketsCrea ticket

Corpo della richiesta

{
  "contactId": "uuid",         // obrigatório
  "status": "open",            // open | pending | closed
  "channel": "whatsapp",       // whatsapp | sms | telegram
  "whatsappId": "uuid",        // canal WhatsApp a usar
  "queueId": "uuid",           // fila/departamento
  "userId": "uuid"             // agente responsável
}

Risposta

{
  "ticket": {
    "id": "uuid",
    "status": "open",
    "channel": "whatsapp",
    "createdAt": "2026-01-15T10:30:00Z"
  }
}
PUT/api/v2/tickets/:ticketIdAggiorna ticket

Parametri

ticketId·uuidobbligatorio

ID del ticket

Corpo della richiesta

{
  "status": "closed",          // open | pending | closed
  "userId": "uuid",            // reatribuir agente
  "queueId": "uuid"            // mover para fila
}

Risposta

{
  "ticket": { "id": "uuid", "status": "closed", "updatedAt": "2026-01-15T12:00:00Z" }
}

Messaggi di un ticket

I messaggi sono annidati sotto il ticket. Per inviare un messaggio, usa POST /tickets/:id/messages.

GET/api/v2/tickets/:ticketId/messagesElenca i messaggi del ticket

Parametri

ticketId·uuidobbligatorio

ID del ticket

pageNumber·integer

Pagina (default: 1)

pageSize·integer

Risultati per pagina (default: 20)

Risposta

{
  "messages": [
    {
      "id": "uuid",
      "body": "Olá, preciso de ajuda",
      "fromMe": false,
      "mediaType": null,
      "mediaUrl": null,
      "ack": 3,
      "createdAt": "2026-01-15T10:30:00Z"
    }
  ],
  "count": 15,
  "hasMore": false
}
POST/api/v2/tickets/:ticketId/messages60 req/min por API KeyInvia messaggio

Parametri

ticketId·uuidobbligatorio

ID del ticket

Corpo della richiesta

{
  "body": "Olá! Como posso ajudar?",  // obrigatório (texto ou caption)
  "mediaUrl": "https://...",           // URL de imagem/documento/áudio
  "mediaType": "image",               // image | document | audio | video
  "quotedMsgId": "uuid"               // responder a mensagem específica
}

Risposta

{
  "message": {
    "id": "uuid",
    "body": "Olá! Como posso ajudar?",
    "fromMe": true,
    "ack": 1,
    "createdAt": "2026-01-15T10:31:00Z"
  }
}

Contatti

Gestione completa dei contatti. Un contatto può avere più ticket su più canali.

GET/api/v2/contactsElenca contatti

Parametri

searchParam·string

Cerca per nome, numero o email

pageNumber·integer

Pagina (default: 1)

pageSize·integer

Risultati per pagina (default: 20)

Risposta

{
  "contacts": [
    {
      "id": "uuid",
      "name": "João Silva",
      "number": "351910000000",
      "email": "joao@exemplo.pt",
      "profilePicUrl": "https://...",
      "isGroup": false,
      "createdAt": "2026-01-10T09:00:00Z"
    }
  ],
  "count": 150,
  "hasMore": true
}
GET/api/v2/contacts/:contactIdOttieni contatto per ID

Parametri

contactId·uuidobbligatorio

ID del contatto

Risposta

{
  "contact": {
    "id": "uuid",
    "name": "João Silva",
    "number": "351910000000",
    "email": "joao@exemplo.pt",
    "extraInfo": [{ "name": "NIF", "value": "123456789" }],
    "createdAt": "2026-01-10T09:00:00Z"
  }
}
POST/api/v2/contactsCrea contatto

Corpo della richiesta

{
  "name": "João Silva",           // obrigatório
  "number": "351910000000",       // obrigatório
  "email": "joao@exemplo.pt",
  "profilePicUrl": "https://...",
  "extraInfo": [
    { "name": "NIF", "value": "123456789" }
  ]
}

Risposta

{
  "contact": {
    "id": "uuid",
    "name": "João Silva",
    "number": "351910000000",
    "createdAt": "2026-01-15T10:00:00Z"
  }
}
PUT/api/v2/contacts/:contactIdAggiorna contatto

Parametri

contactId·uuidobbligatorio

ID del contatto

Corpo della richiesta

{
  "name": "João M. Silva",
  "email": "joao.novo@exemplo.pt",
  "extraInfo": [{ "name": "Empresa", "value": "Acme Lda" }]
}

Risposta

{
  "contact": { "id": "uuid", "name": "João M. Silva", "updatedAt": "2026-01-15T11:00:00Z" }
}

Campagne

Invio in massa a gruppi di contatti via WhatsApp o SMS, con pianificazione e controllo dello stato.

⚠️ Le campagne sono soggette alle politiche di uso accettabile di WhatsApp Business. L'invio in massa non autorizzato può comportare il blocco del numero.
GET/api/v2/campaignsElenca campagne

Parametri

status·string

in attesa | in esecuzione | terminato | annullato

pageNumber·integer

Pagina (default: 1)

Risposta

{
  "campaigns": [
    {
      "id": "uuid",
      "name": "Promoção Verão 2026",
      "status": "finished",
      "scheduledAt": "2026-06-01T09:00:00Z",
      "sentCount": 342,
      "failedCount": 3,
      "createdAt": "2026-05-20T10:00:00Z"
    }
  ],
  "count": 8,
  "hasMore": false
}
POST/api/v2/campaignsCrea campagna

Corpo della richiesta

{
  "name": "Promoção Verão 2026",  // obrigatório
  "message": "Olá {{name}}! ...", // obrigatório (suporta {{name}}, {{number}})
  "whatsappId": "uuid",           // canal a usar
  "contactGroupId": "uuid",       // grupo de contactos alvo
  "scheduledAt": "2026-06-01T09:00:00Z"  // null = envio imediato
}

Risposta

{
  "campaign": {
    "id": "uuid",
    "name": "Promoção Verão 2026",
    "status": "pending",
    "createdAt": "2026-05-20T10:00:00Z"
  }
}

Agenti IA

Gli agenti IA rispondono automaticamente ai ticket usando LLM (Cortecs Sovereign Cloud — conformità EU AI Act). Possono usare strumenti come KiviCare, calendario, CRM e knowledge base.

GET/api/v2/ai-agentsElenca agenti IA

Nessun parametro obbligatorio.

Risposta

{
  "agents": [
    {
      "id": "uuid",
      "name": "Maria — Assistente FamilyClinic",
      "model": "cortecs:llama-4-maverick",
      "isActive": true,
      "enabledIntegrations": ["kivicare"],
      "handoffEnabled": true,
      "createdAt": "2026-03-01T10:00:00Z"
    }
  ]
}
POST/api/v2/ai-agents/assignAssegna agente IA a un ticket

Corpo della richiesta

{
  "ticketId": "uuid",   // obrigatório
  "agentId": "uuid"     // obrigatório — null para remover agente
}

Risposta

{
  "ticket": { "id": "uuid", "aiAgentId": "uuid", "updatedAt": "2026-01-15T10:00:00Z" }
}

Webhooks

Configura un endpoint HTTPS per ricevere eventi in tempo reale. WhatSMS effettua un POST con un payload JSON firmato con HMAC-SHA256.

Header di firma

X-WhatSMS-Signature: sha256=<hmac_hex>

Verifica la firma con il tuo webhook secret per garantire che la richiesta provenga da WhatSMS.

Eventi disponibili

EventoDescrizione
message.receivedNuovo messaggio ricevuto da un contatto
message.sentMessaggio inviato con successo
message.ackConferma di consegna/lettura (ack 1–5)
ticket.createdNuovo ticket creato
ticket.updatedTicket aggiornato (stato, agente, coda)
ticket.closedTicket chiuso
contact.createdNuovo contatto creato
contact.updatedContatto aggiornato
campaign.finishedCampagna terminata

Payload di esempio — message.received

{
  "event": "message.received",
  "tenantId": "uuid",
  "timestamp": "2026-01-15T10:30:00Z",
  "data": {
    "message": {
      "id": "uuid",
      "body": "Olá, preciso de ajuda",
      "fromMe": false,
      "mediaType": null,
      "createdAt": "2026-01-15T10:30:00Z"
    },
    "ticket": { "id": "uuid", "status": "open" },
    "contact": { "id": "uuid", "name": "João Silva", "number": "351910000000" }
  }
}

Limiti di velocità

I limiti sono per API Key e per finestra di 1 minuto. Quando raggiungi il limite ricevi un 429 con l'header Retry-After in secondi.

Punto finaleLimite
Tutti gli endpoint v2300 req/min por API Key
POST /tickets/:id/messages60 req/min por API Key
POST /campaigns10 req/min por API Key

SDK e Integrazioni

Integra WhatSMS nel tuo stack con il node n8n ufficiale o direttamente via HTTP in qualsiasi linguaggio.

⚡

Nodo n8n

Node nativo per n8n con trigger di webhook e azioni di invio messaggi. Disponibile nel marketplace di n8n.

Presto disponibile
🔌

HTTP / REST

API REST standard compatibile con qualsiasi linguaggio — JavaScript, Python, PHP, Go, ecc. Usa lo Swagger interattivo per esplorare e testare tutti gli endpoint.

Apri Swagger →

Esempio — inviare un messaggio con fetch

const res = await fetch("https://api.whatsms.pt/api/v2/tickets/{ticketId}/messages", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_live_xxxxxxxxxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ body: "Olá! Como posso ajudar?" })
});

const { message } = await res.json();
console.log(message.id);

Documentazione completa e testa tutti gli endpoint nello Swagger interattivo.

⚡ Apri Swagger