WhatSMS/API Docs
Swagger →Kostenlos starten
EinführungAuthentifizierungFehlerTickets↳ NachrichtenKontakteKampagnenKI-AgentenWebhooksRatenbegrenzungenSDKs & n8n
⚡ Interaktives Swagger

Einführung

Mit der WhatSMS REST-API können Sie Nachrichten senden, Kontakte, Tickets und Kampagnen verwalten und Echtzeit-Ereignisse über Webhooks empfangen. Jede Anfrage wird per API Key authentifiziert und pro Tenant isoliert.

v2

Basis-URL

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

Vollständiges CRUD, strukturierte Paginierung, Medien-Unterstützung und Rate Limiting pro API Key.

🔑

API Key pro Tenant

Jedes Konto hat seinen eigenen API Key. Erstellen und widerrufen unter Einstellungen → Integrationen → API Keys.

🔒

HTTPS erforderlich

Alle Anfragen müssen HTTPS verwenden. HTTP-Anfragen werden automatisch abgelehnt.

🇪🇺

DSGVO-nativ

Die Daten verbleiben auf europäischen Servern. Native DSGVO-Konformität, ohne Daten außerhalb der EU zu senden.

Authentifizierung

Jede Anfrage erfordert den Authorization-Header mit dem API Key im Bearer-Format. Erhalten Sie Ihren API Key unter Einstellungen → Integrationen → API Keys.

Erforderlicher Header

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

cURL-Beispiel

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

⚠️ Sicherheit

Geben Sie den API Key niemals in clientseitigem Code oder öffentlichen Repositories preis. Verwenden Sie Umgebungsvariablen auf dem Server. Wenn ein Key kompromittiert wird, widerrufen Sie ihn sofort unter Einstellungen → Integrationen → API Keys.

Fehler

Die API verwendet standardmäßige HTTP-Statuscodes. Der Fehlerkörper folgt stets dieser Struktur:

Fehlerformat

{ "error": "Mensagem descritiva do erro" }
CodeBedeutung
200Erfolg
201Erfolgreich erstellt
400Ungültige Anfrage — fehlende oder falsche Parameter
401Nicht authentifiziert — ungültiger oder fehlender API Key
403Keine Berechtigung für diese Ressource
404Ressource nicht gefunden
429Rate Limit erreicht — vor erneutem Versuch warten
500Interner Serverfehler

Tickets

Ein Ticket repräsentiert eine Konversation mit einem Kontakt. Es bündelt Nachrichten, Kanal, Status und den zuständigen Agenten.

GET/api/v2/ticketsTickets auflisten

Parameter

status·string

Nach Status filtern: open, pending, closed

contactId·uuid

Nach Kontakt filtern

pageNumber·integer

Seite (default: 1)

pageSize·integer

Ergebnisse pro Seite (default: 20, max: 100)

Antwort

{
  "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/:ticketIdTicket nach ID abrufen

Parameter

ticketId·uuiderforderlich

Ticket-ID

Antwort

{
  "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/ticketsTicket erstellen

Anfrage-Body

{
  "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
}

Antwort

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

Parameter

ticketId·uuiderforderlich

Ticket-ID

Anfrage-Body

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

Antwort

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

Nachrichten eines Tickets

Die Nachrichten sind unter dem Ticket verschachtelt. Um eine Nachricht zu senden, verwenden Sie POST /tickets/:id/messages.

GET/api/v2/tickets/:ticketId/messagesTicket-Nachrichten auflisten

Parameter

ticketId·uuiderforderlich

Ticket-ID

pageNumber·integer

Seite (default: 1)

pageSize·integer

Ergebnisse pro Seite (default: 20)

Antwort

{
  "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 KeyNachricht senden

Parameter

ticketId·uuiderforderlich

Ticket-ID

Anfrage-Body

{
  "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
}

Antwort

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

Kontakte

Vollständige Kontaktverwaltung. Ein Kontakt kann mehrere Tickets über mehrere Kanäle haben.

GET/api/v2/contactsKontakte auflisten

Parameter

searchParam·string

Nach Name, Nummer oder E-Mail suchen

pageNumber·integer

Seite (default: 1)

pageSize·integer

Ergebnisse pro Seite (default: 20)

Antwort

{
  "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/:contactIdKontakt nach ID abrufen

Parameter

contactId·uuiderforderlich

Kontakt-ID

Antwort

{
  "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/contactsKontakt erstellen

Anfrage-Body

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

Antwort

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

Parameter

contactId·uuiderforderlich

Kontakt-ID

Anfrage-Body

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

Antwort

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

Kampagnen

Massenversand an Kontaktgruppen über WhatsApp oder SMS, mit Planung und Statuskontrolle.

⚠️ Kampagnen unterliegen den Richtlinien zur akzeptablen Nutzung von WhatsApp Business. Nicht autorisierter Massenversand kann zur Sperrung der Nummer führen.
GET/api/v2/campaignsKampagnen auflisten

Parameter

status·string

anstehend | laufend | beendet | abgebrochen

pageNumber·integer

Seite (default: 1)

Antwort

{
  "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/campaignsKampagne erstellen

Anfrage-Body

{
  "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
}

Antwort

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

KI-Agenten

KI-Agenten beantworten Tickets automatisch mithilfe von LLMs (Cortecs Sovereign Cloud — konform mit dem EU AI Act). Sie können Tools wie KiviCare, Kalender, CRM und Wissensdatenbank nutzen.

GET/api/v2/ai-agentsKI-Agenten auflisten

Keine erforderlichen Parameter.

Antwort

{
  "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/assignKI-Agent einem Ticket zuweisen

Anfrage-Body

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

Antwort

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

Webhooks

Konfigurieren Sie einen HTTPS-Endpoint, um Echtzeit-Ereignisse zu empfangen. WhatSMS führt einen POST mit einem mit HMAC-SHA256 signierten JSON-Payload aus.

Signatur-Header

X-WhatSMS-Signature: sha256=<hmac_hex>

Überprüfen Sie die Signatur mit Ihrem Webhook-Secret, um sicherzustellen, dass die Anfrage von WhatSMS stammt.

Verfügbare Ereignisse

EreignisBeschreibung
message.receivedNeue Nachricht von einem Kontakt empfangen
message.sentNachricht erfolgreich gesendet
message.ackZustell-/Lesebestätigung (ack 1–5)
ticket.createdNeues Ticket erstellt
ticket.updatedTicket aktualisiert (Status, Agent, Warteschlange)
ticket.closedTicket geschlossen
contact.createdNeuer Kontakt erstellt
contact.updatedKontakt aktualisiert
campaign.finishedKampagne abgeschlossen

Beispiel-Payload — 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" }
  }
}

Ratenbegrenzungen

Die Limits gelten pro API Key und pro 1-Minuten-Fenster. Wenn Sie das Limit erreichen, erhalten Sie einen 429 mit dem Retry-After-Header in Sekunden.

EndpunktLimit
Alle v2-Endpoints300 req/min por API Key
POST /tickets/:id/messages60 req/min por API Key
POST /campaigns10 req/min por API Key

SDKs & Integrationen

Integrieren Sie WhatSMS in Ihren Stack mit dem offiziellen n8n-Node oder direkt per HTTP in jeder Sprache.

⚡

n8n-Node

Nativer n8n-Node mit Webhook-Trigger und Aktionen zum Senden von Nachrichten. Verfügbar im n8n-Marketplace.

Demnächst
🔌

HTTP / REST

Standard-REST-API, kompatibel mit jeder Sprache — JavaScript, Python, PHP, Go usw. Nutzen Sie das interaktive Swagger, um alle Endpoints zu erkunden und zu testen.

Swagger öffnen →

Beispiel — eine Nachricht mit fetch senden

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

Vollständige Dokumentation und testen Sie alle Endpoints im interaktiven Swagger.

⚡ Swagger öffnen