Skip to main content
Web Callback places a click-to-call from your backend: you name a destination, Wave dials it through its telephony backend and bridges the call.

​
Placing a call

POST /v1/callback with at least a to number. See the Quickstart and the API Reference.

​
Connecting the answered call

When the customer answers a production callback, Wave must know where to connect the call. Do this before you go live:
  • Bind an IVR menu to your number. A bound IVR always comes first.
  • Or set a connect number: in the dashboard, open Settings → Connect number (owner or admin only). Wave calls this Saudi mobile or landline number and connects the customer; the person who answers sees your project’s number. If nobody answers, the customer hears a short message, then the call ends.
With nothing set up, the customer hears a short “not available” message, then the call ends. A sandbox callback does not change: it plays the sandbox test message.

​
Call lifecycle

A callback is created with status: "initiated" and returns 202 immediately. The call then progresses through its lifecycle as the telephony backend reports it — answered (with answered_at), then ended (with duration). Each transition fires the matching webhook (call.answered, call.ended), and the final status and duration are written to the call record.
Treat the 202 as “accepted,” not “completed.” Subscribe to webhooks — or poll GET /v1/calls — to follow the call to answered / ended.

​
Call logs

Every callback is recorded. Retrieve them with GET /v1/calls — cursor-paginated (cursor, limit up to 100), numbers masked — or view them on the Call Logs page in the dashboard. See the API Reference for the full request/response.

​
Listing, reading and cancelling callbacks

  • GET /v1/callbacks lists your callbacks, newest first, paged with page and page_size (up to 100). Filter by status, queue_id, from and to; with no from or to, the last 7 days are returned. Requires the calls:read scope.
  • GET /v1/callbacks/:id returns one callback by the callback_id from the 202 answer. Requires the calls:read scope.
  • DELETE /v1/callbacks/:id cancels a callback that is still initiated or ringing; the status becomes cancelled and a call.cancelled webhook is sent. A callback past ringing returns 409 CALLBACK_NOT_CANCELLABLE. Requires the calls:write scope.
A key sees only the callbacks of its own environment: the list accepts environment (send only the key’s own value; another value returns 400 VALIDATION_ERROR), and a read or cancel of a callback of the other environment returns 404 CALLBACK_NOT_FOUND. See Sandbox mode. See the API Reference for the full request and response shapes.