For developers

Platform API

Wavely's Platform API lets your own application manage its businesses, branches, teams and members from your server, without opening the dashboard.

What the API does

Your application uses the Platform API server to server, under /platform/v1. With it your app manages Wavely without opening the dashboard:

  • the businesses your app owns, with their settings, branches and teams (called divisions in the API)
  • members (agents), with their routing and visibility settings
  • contacts and their WhatsApp consent
  • channels, WhatsApp numbers, canned responses and canned events
  • conversations and messages: send a WhatsApp message, read history, upload files
  • webhook endpoints and embedded component sessions

An app only sees the businesses it created itself.

Get started

  1. Your app is registered by the Wavely team. You receive a publishable key wvpk_... for embedded components, and one or more secret keys wvsk_....
  2. Each secret key carries scopes, such as directory:read, contacts:write, messages:write, webhooks:manage and embed:sessions. A key's secret shows only once, when it is created or rotated. Store it somewhere safe.
  3. Send the key in the Authorization header. A route that works on one business also needs the Wavely-Organization header.
curl https://WAVELY-HOST/platform/v1/branches \
  -H "Authorization: Bearer wvsk_..." \
  -H "Wavely-Organization: BUSINESS-ID"

A key without the scope a route needs gets 403 insufficient_scope, and details.required_scope names the missing scope.

Request rules

  • A POST that creates something must carry an Idempotency-Key. Repeating the same request with the same key returns the same answer, not duplicate data.
  • A change to versioned data (branches, teams, agents, contacts, channels and more) must carry If-Match with the version from the ETag. A stale version gets 412, and a missing header 428.
  • Lists use cursor and limit (1 to 100), and answer { items, next_cursor }.
  • Errors look like { "error": { "code", "message", "details" } }. A 429 answer includes Retry-After.

Note: See also the Webhooks page to hear about changes, and Embedded components to show Wavely screens inside your app.