API-referentie

Koppel Kyrn aan je eigen applicaties via onze REST API.

Authenticatie

Alle API-requests hebben een API-sleutel nodig via de Authorization-header. Maak API-sleutels aan via Instellingen → Ontwikkelaars.

bash

curl -X POST https://yourdomain.com/api/v1/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instanceName":"my-instance","number":"31612345678","type":"text","message":"Hello!"}'

Base URL

bash

https://yourdomain.com/api/v1

Bericht versturen

POST/api/v1/send

Verstuur een WhatsApp-bericht via je gekoppelde instantie.

Request-body

json

{
  "instanceName": "my-instance",       // string — your instance name
  "number": "31612345678",            // string — recipient phone number (E.164 format)
  "type": "text",                     // "text" | "image" | "video" | "document" | "audio"
  "message": "Hello, world!",          // string — message content (required for type="text")
  "mediaUrl": "https://...",          // string — URL for media (required for image/video/document/audio)
  "fileName": "document.pdf",          // string — file name for documents
  "mimetype": "application/pdf"       // string — MIME type for media
}

Response

json

{
  "success": true,
  "data": {
    "key": { "id": "false_123456789@c.us_9C6D0..." },
    "message": "success"
  }
}

Limieten

Limieten gelden per team en hangen af van je abonnement:

• Free: 5 messages/min
• Starter: 10 messages/min
• Pro: 40 messages/min
• Enterprise: 200 messages/min

Wanneer je de limiet raakt, geeft de API 429 Too Many Requests terug met een Retry-After-header.

Webhooks

Ontvang realtime bericht-events door een webhook-URL in te stellen bij Instellingen. Je webhook-endpoint moet:

1. POST-requests accepteren
2. Binnen 5 seconden 200 OK teruggeven
3. De webhook-signature controleren als die is ingesteld

json

// Incoming webhook payload (messages.upsert event)
{
  "event": "messages.upsert",
  "instance": "my-instance",
  "data": {
    "key": {
      "id": "false_31612345678@c.us_ABC123",
      "remote": "31612345678@c.us",
      "fromMe": false
    },
    "message": {
      "conversation": "Hi there!"
    },
    "messageType": "conversation",
    "pushName": "John"
  }
}

Foutcodes

Code	Betekenis
400	Ongeldige request of payload
401	Niet geautoriseerd: API-sleutel ontbreekt of is ongeldig
403	Geen toegang: webhook-token komt niet overeen
404	Instantie niet gevonden of niet verbonden
429	Limiet overschreden
500	Interne serverfout