API Quickstart

This page gets you from an API key to a sent message in a few commands. Replace YOUR_DOMAIN with your deployment host and lw_live_... with a key from Settings → API Keys (see Authentication).

1. Check connectivity

Confirm your key works with the health endpoint (any valid key, no scope needed):


curl https://YOUR_DOMAIN/api/v1/health \
  -H "Authorization: Bearer lw_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response


{ "ok": true, "version": "1.0.0" }

2. Send a WhatsApp message

Send a message from a connected, ready number. Pass a phone number (with country code) or a full WhatsApp jid in to. Requires the messages:write scope.


curl -X POST https://YOUR_DOMAIN/api/v1/messages \
  -H "Authorization: Bearer lw_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "919812345678",
    "text": "Hi! Thanks for reaching out."
  }'

Response (202)


{ "status": "sent", "to": "919812345678@s.whatsapp.net", "from": "n1a2b3c" }

If you omit from, Loopwave sends from the first connected number that’s ready. To send from a specific number, pass its id as from. If no number is ready, you’ll get 409 no_ready_session.

3. Create a contact

Requires the contacts:write scope. name and phone are required.


curl -X POST https://YOUR_DOMAIN/api/v1/contacts \
  -H "X-API-Key: lw_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Asha Rao",
    "phone": "919812345678",
    "lifecycle": "lead",
    "tags": ["website"]
  }'

4. Open a ticket

Requires the tickets:write scope. Only subject is required.


curl -X POST https://YOUR_DOMAIN/api/v1/tickets \
  -H "X-API-Key: lw_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Refund not received",
    "customerName": "Asha Rao",
    "customerPhone": "919812345678",
    "priority": "high"
  }'

Handling errors

Status	Meaning	Fix
`401 invalid_api_key`	Missing or bad key	Check the header and that the key is enabled.
`403 insufficient_scope`	Key lacks the scope	Add the scope, or use a `*` key.
`402 license_locked`	License expired/revoked	Renew/activate the license.
`409 no_ready_session`	No connected number	Connect a number and wait for `ready`.
`429 rate_limited`	Over the rate limit	Back off; see Rate limits.

Full endpoint reference→

Browse every endpoint with curl and JSON examples.