Quickstart

This guide takes you from zero to a delivered WhatsApp template message in five minutes. You'll create an API token, call /v1/me to confirm authentication, and trigger a real template send.

What you need

• A Qyvo workspace with at least one connected WhatsApp number — sign up at qyvo.io if you don't have one.
• A WhatsApp template that has been approved by Meta. New workspaces get a hello_world template approved by default.
• A phone number you can receive messages on, in international format (e.g. +14155550123).
• curl, or any HTTP client.

1. Create an API token

Sign in to your workspace and open Settings → API Tokens. Click Create token, name it (e.g. quickstart), and copy the value.

The token is only displayed for 90 seconds after creation, then masked forever. If you lose it, revoke it and generate a new one.

The token is a Laravel Passport personal access token issued with the mcp scope. The same token works for the REST API and the MCP server.

2. Confirm the token works

Every request must include Authorization: Bearer <token>. Call /v1/me to verify everything is wired up:

curl https://www.qyvo.io/api/v1/me \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

You should get a JSON payload describing your account and workspace:

{
  "id": 42,
  "email": "[email protected]",
  "name": "Romain",
  "tenant": {
    "id": "01HZX9...",
    "name": "Acme Co."
  }
}

A 401 Unauthorized means the token is wrong or revoked — generate a new one. See Errors for the full catalogue.

3. Find a template id

Templates are referenced by UUID, not by name. List your approved templates:

curl -X POST https://www.qyvo.io/api/v1/actions/list-templates \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{"status": "APPROVED"}'

[
  {
    "id": "01J0AB...",
    "name": "hello_world",
    "category": "UTILITY",
    "status": "APPROVED",
    "languages": ["en"],
    "created_at": "2026-04-15T10:32:00+00:00"
  }
]

Copy the id of the template you want to send.

4. Send your first template message

POST /v1/actions/send-template-message with the contact's phone, your template_id, and (if the template has placeholders) the variables:

curl -X POST https://www.qyvo.io/api/v1/actions/send-template-message \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+14155550123",
    "template_id": "01J0AB...",
    "language": "en"
  }'

If the template has variables (e.g. Hello {{1}}, your order {{2}} is ready), pass them keyed by placeholder name:

curl -X POST https://www.qyvo.io/api/v1/actions/send-template-message \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+14155550123",
    "template_id": "01J0AB...",
    "language": "en",
    "variables": {
      "1": "Romain",
      "2": "ORD-1042"
    }
  }'

A successful response contains the Qyvo message id, the underlying Meta message id, and the contact id (the contact is created automatically if it didn't exist):

{
  "id": "01J1Z...",
  "status": "sent",
  "whatsapp_message_id": "wamid.HBgL...",
  "contact_id": "01J1Y..."
}

If language is not approved on Meta, Qyvo automatically picks any approved translation of the template instead of failing. To force a specific language, pass it explicitly — and make sure that translation is approved.

5. Watch it deliver

Open the Inbox in your dashboard — you'll see the message land in the conversation with that contact. Status updates (sent → delivered → read) propagate in real time.

Subscribe to webhooks to receive the same updates programmatically — see Webhooks.

Next steps

• Authentication — token scopes, rotation, and security.
• Errors — the full error code catalogue.
• Send text message — free-form replies during the 24-hour customer service window.
• MCP Quickstart — drive the same workspace from Claude Desktop, Cursor, ChatGPT, or n8n.