WAVV Public API v3

Read your team's call data over REST, and receive call events in real time over signed webhooks. The two share one canonical call shape, so what you poll and what you're pushed are identical. The same reads are also served to AI assistants through the WAVV MCP server.

Version
3.0.0
Format
JSON over HTTPS
Base URL
https://api.wavv.com/v3

Getting Started

Overview

The v3 Public API gives you programmatic access to your team's call activity in several ways:

  • REST — GET /calls, plus per-call recording and transcript endpoints, for backfills, reconciliation, and on-demand lookups; and /inbound-flows to read and change what happens when someone calls the team's numbers.
  • Webhooks — call.* and message.* events pushed to an HTTPS endpoint you register, for real-time work.
  • MCP — the WAVV MCP server gives Claude, ChatGPT, and other AI assistants the same call reads as tools, plus tools for working call boards. See MCP server.

Both call surfaces serialize a call through the same code path, so a call fetched from GET /calls/{id} and the data object inside a call.ended webhook are field-for-field identical. Build your model once.

All requests and responses are JSON. Timestamps are ISO 8601 in UTC (e.g. 2026-05-21T14:30:00Z). Phone numbers are unformatted 10-digit NANP strings (e.g. 5125551234).

Getting Started

Authentication

Every REST endpoint requires an API key, passed as a Bearer token in the Authorization header:

Authorization: Bearer <your_api_key>

A missing, malformed, or revoked key returns 401 with error code INVALID_API_KEY.

Keys are team-scoped: a key can only ever read calls belonging to the team it was issued for. There is no cross-team or agency-wide call access in this version, and no team id is accepted as a parameter — the key determines the team. Manage keys in the WAVV Integrations panel.

Webhooks are not authenticated with an API key. Each webhook has its own signing secret and is verified by signature — see Verifying signatures.

Getting Started

Rate limits

Requests are counted in one-minute windows, in several buckets at once. A request has to fit in every bucket that applies to it:

Per credential
300 requests a minute for each API key, and 60 a minute for each signed-in user. Two keys on the same team have a bucket each; one person signed in to two assistants shares one.
Heavy reads
10 a minute per credential, on top of the per-credential limit, for the reads that cost the most: call lists with transcripts (includeTranscripts), and, for signed-in users, transcripts. An API key fetching one transcript at a time counts it as an ordinary read. Some MCP tools are heavy reads too.
Per team
600 requests a minute across every credential on the team, so several integrations and assistants together cannot exceed it.

Limits are never by IP address. Assistants such as Claude and ChatGPT call from their own servers, so an IP limit would make customers share one another's budget.

Over a limit, REST answers 429 with code RATE_LIMITED and a Retry-After header giving the whole seconds until that bucket's window resets:

HTTP/1.1 429 Too Many Requests
Retry-After: 23

Wait at least that long. A rejected request still counts against the window it was made in, so retrying in a tight loop only keeps you limited.

The MCP server and the REST API share the same counters — a tool call and a REST request cost the same, so switching between the two does not double your budget. Requests rejected before they reach an endpoint — a 401, a 403, or a 400 for a malformed parameter — are not counted. A 400 an endpoint raises after reading the request is.

Getting Started

Pagination and filtering

GET /calls returns calls newest-first and pages with a keyset cursor.

Cursor
Each response carries a nextCursor. Pass it back as the cursor query parameter to get the next page. nextCursor is null on the last page. The value is the startedAt of the last returned call — treat it as opaque; the format may change.
Page size
limit defaults to 50 and is capped at 200. A value above the cap is reduced to 200 rather than rejected. A value that is zero, negative, or not a number falls back to the default of 50. With includeTranscripts=true the cap is 25, since each call then carries its full transcript.
Time range
startedAfter and startedBefore bound startedAt inclusively, and each may be used on its own. Send both as ISO 8601 — a value that can't be parsed as a date is treated as absent, so validate before sending to be sure you get the window you intend.
Stable paging
Paging is keyset rather than offset, so calls created while you page through will not shift or duplicate the rows you have already read. The cursor has one-second resolution; deduplicate on id if your integration requires exactness across page boundaries.

Webhooks

Verifying signatures

Every delivery carries an X-WAVV-Signature header:

X-WAVV-Signature: t=1779720600,v1=6f2a…c91b
  • t — Unix timestamp in seconds, stamped fresh at send time (so a retry carries a new t).
  • v1 — hex HMAC-SHA256 of the timestamp, a literal dot, and the raw body concatenated together, keyed with the webhook's signing secret.

To verify, in order:

  • Read the raw request body as bytes, before any JSON parsing. Re-serializing a parsed body changes the bytes and the signatures will not match.
  • Recompute the HMAC over t + "." + rawBody with your signing secret.
  • Compare against v1 in constant time (crypto.timingSafeEqual, not ===).
  • Reject the delivery if |now - t| exceeds your tolerance. 300 seconds is a common choice; this check is what prevents a captured delivery from being replayed later.

The signing secret is prefixed whsec_ and is available in the Integrations panel. Because verification requires the secret itself, it remains retrievable there — handle it with the same care as a password. Deleting a webhook also deletes its signing secret.

const crypto = require('node:crypto');

function verify(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(',').map((kv) => kv.split('=')));
  const t = Number(parts.t);
  if (!Number.isFinite(t)) return false;
  if (Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  const a = Buffer.from(expected, 'hex');
  const b = Buffer.from(parts.v1 ?? '', 'hex');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Webhooks

Delivery and retries

Register endpoints in the WAVV Integrations panel: give the webhook a name, an HTTPS URL, and the set of events it should receive. Each webhook can subscribe to any combination of the events, and a team can have several.

Request
POST with Content-Type: application/json and the X-WAVV-Signature header. Your endpoint has 10 seconds to respond before the attempt times out.
Success
Any 2xx acknowledges the delivery. Any other status, including a redirect, is treated as a failure and retried. Acknowledge first and process the payload afterwards.
Retries
Up to 5 attempts with exponential backoff starting at 1 second. Each webhook retries independently, so a failing endpoint does not delay or duplicate delivery to your other endpoints. A delivery that fails all five attempts is not retried further.
Rate
Deliveries are grouped per webhook and paced at roughly 10 per second. A slow endpoint throttles only its own queue.
Make handlers idempotent
Delivery is at-least-once, so the same event may arrive more than once, and because each event is queued independently, events for one call may arrive out of order. Deduplicate on (event, data.id) and design each handler to be safely replayable.
URL requirements
The URL must be an absolute http or https URL on a publicly routable host. localhost and addresses in loopback, RFC-1918 private, link-local, and CGNAT ranges are not accepted. This is validated at registration and confirmed again before each delivery.

Calls

List calls

GET/calls

Returns the team's calls, newest first. Every parameter is optional.

transcript is omitted from this response to keep pages small. Fetch it per-call from GET /calls/{id}/transcript, or, to read many transcripts at once (scoring calls against a script, comparing openers), set includeTranscripts=true: each call then carries a transcript field, pages hold at most 25 calls because a transcript can run to tens of kilobytes, and the request counts as a heavy read.

Filters combine with AND.

The direction filter selects by call type: outbound returns the calls your team dialed, inbound returns calls received on a team number, including forwarded ones, and all — the default — returns both, merged newest first. Internal call types such as whispers and transfers are not returned by any direction, although such a call fetched by id reports direction: outbound.

Calls made by an agent who has since left the team are still returned by every filter: userId takes any agent who appears on a call, and the contact filters (contactId, contactName) search your team's CRM locations, not just its current members.

With an API key, a repeated limit uses its first value, and a repeated campaignId, startedAfter, startedBefore or cursor is ignored. With a Sign in with WAVV token, any repeated parameter is rejected with INVALID_REQUEST.

Query parameters
ParameterTypeDescription
directionstringoptWhich calls to return: outbound (calls the team dialed), inbound (calls received, including forwarded ones), or all. Defaults to all. A repeated or unrecognised value is rejected with INVALID_REQUEST rather than falling back to the default. One of: inbound, outbound, all.
campaignIdstring (uuid)optRestrict to a single dialing campaign. Must be a UUID — anything else is rejected with INVALID_REQUEST rather than simply matching no calls. With an API key, an empty value is ignored.
userIdstringoptOnly this agent's calls: the agent's id in your CRM, the same value as a call's userId. An id that matches nobody on the team returns an empty page, not an error, so a typo looks exactly like an agent with no calls.
phonestringoptOnly calls with the contact on this number: matched against phone on outbound calls, and against callerId on inbound and forwarded ones, since there the contact is the one calling. Your own WAVV numbers are never matched, so this finds a contact's calls in both directions. Any format is accepted: non-digits are stripped and a leading country code 1 is dropped, so +1 (512) 555-1234 matches 5125551234. At least 7 characters.
contactIdstringoptOnly calls with this contact: the contact's id in your CRM, the same value as a call's contactId. Inbound calls only carry a contactId when the caller matched a known contact.
contactNamestringoptOnly calls whose contactName contains this text, ignoring case. At least 3 characters. Without startedAfter, only the 90 days before startedBefore (or before now) are searched; send startedAfter to search further back.
startedAfterstring (date-time)optOnly calls with startedAt at or after this instant. Unparseable values are ignored.
startedBeforestring (date-time)optOnly calls with startedAt at or before this instant. Unparseable values are ignored.
cursorstringoptThe nextCursor from a previous response. Omit for the first page. An unparseable value is ignored, which returns the first page again.
limitintegeroptPage size, 1–200. Defaults to 50. A larger value is reduced to 200; a value that is zero, negative, or not a number falls back to 50. With includeTranscripts=true, a value above 25 (including the default) is reduced to 25.
includeTranscriptsbooleanopttrue (or 1) to give each call its full transcript — null for a call that has none, or none yet. Pages then hold at most 25 calls, and the request counts as a heavy read. Defaults to false. Any value other than true, false, 1, or 0 is rejected with INVALID_REQUEST.
Responses
200OK — a CallListEnvelope.
400direction was not one of inbound, outbound, all; campaignId was not a UUID; phone was shorter than 7 characters or contactName shorter than 3; userId or contactId was empty; includeTranscripts was not true, false, 1, or 0; or a parameter was sent more than once — INVALID_REQUEST.
401Credential missing, malformed, revoked, or expired — INVALID_API_KEY.
403The signed-in user's role cannot use the API, or they are not on an active team — FORBIDDEN.
429Over a rate limit — RATE_LIMITED, with Retry-After.
500Failed to list calls — SERVER_ERROR.
503The request took too long — QUERY_TIMEOUT. Narrow the date range or filters.
Response shape
{
  "data": [
    {
      "id": "3c9a17b4-2f5e-4d81-b0a7-6e2c9d4f1a03",
      "teamId": "8f3b2c10-4e7a-4b1c-9d2e-1a2b3c4d5e6f",
      "userId": "crm-user-4471",
      "groupId": "west-region",
      "subgroupId": "team-4",
      "campaignId": "5d1e8a72-9c34-4f60-8b2a-7e0d3c5f9b18",
      "direction": "outbound",
      "phone": "5125551234",
      "callerId": "5125559876",
      "contactId": "crm-99213",
      "contactName": "Dana Reyes",
      "startedAt": "2026-05-21T14:28:12Z",
      "answeredAt": "2026-05-21T14:28:19Z",
      "endedAt": "2026-05-21T14:30:00Z",
      "seconds": 101,
      "outcome": "HUNG_UP",
      "disposition": "Interested",
      "human": true,
      "note": "Sending pricing.",
      "summary": "Prospect asked for pricing on the multi-line plan.",
      "recorded": true
    }
  ],
  "nextCursor": "2026-05-21T14:28:12Z"
}

Calls

Get a call

GET/calls/{id}

Returns one call. transcript is excluded, as it is from the list endpoint unless the list is asked for includeTranscripts.

A call that exists but belongs to another team returns 404, not 403 — the API does not confirm the existence of calls outside your team.

Path parameters
ParameterTypeDescription
idstring (uuid)reqThe call's unique identifier.
Responses
200OK — a Call.
400id was not a UUID — INVALID_REQUEST.
401Credential missing, malformed, revoked, or expired — INVALID_API_KEY.
403The signed-in user's role cannot use the API, or they are not on an active team — FORBIDDEN.
404Call not found, or not on this team — NOT_FOUND.
429Over a rate limit — RATE_LIMITED, with Retry-After.
500Failed to fetch call — SERVER_ERROR.
Response shape
{
  "id": "3c9a17b4-2f5e-4d81-b0a7-6e2c9d4f1a03",
  "teamId": "8f3b2c10-4e7a-4b1c-9d2e-1a2b3c4d5e6f",
  "userId": "crm-user-4471",
  "groupId": "west-region",
  "subgroupId": "team-4",
  "campaignId": "8f3b2c10-4e7a-4b1c-9d2e-1a2b3c4d5e6f",
  "direction": "inbound",
  "phone": "5125551234",
  "callerId": "5125559876",
  "contactId": "crm-99213",
  "contactName": "Dana Reyes",
  "startedAt": "2026-05-21T14:30:00Z",
  "answeredAt": "2026-05-21T14:30:00Z",
  "endedAt": "2026-05-21T14:30:00Z",
  "seconds": 101,
  "outcome": "BUSY",
  "disposition": "Interested",
  "human": true,
  "note": "string",
  "summary": "string",
  "recorded": true
}

Calls

Get a recording URL

GET/calls/{id}/recording

Returns a freshly signed URL for the call's audio recording.

The URL is generated per request and is valid for the window given in expiresAt, currently 72 hours. Store the call id rather than the URL, and request a new one whenever you need access.

A 404 covers both a call that has no recording and a call id that isn't available to your credential. Read recorded on the call object beforehand when you need to tell the two apart.

Path parameters
ParameterTypeDescription
idstring (uuid)reqThe call's unique identifier.
Responses
200OK — a RecordingUrl.
400id was not a UUID — INVALID_REQUEST.
401Credential missing, malformed, revoked, or expired — INVALID_API_KEY.
403The signed-in user's role cannot use the API, or they are not on an active team — FORBIDDEN.
404Call not found, or the call has no recording — NOT_FOUND.
429Over a rate limit — RATE_LIMITED, with Retry-After.
500Failed to fetch recording — SERVER_ERROR.
Response shape
{
  "url": "https://example.com",
  "expiresAt": "2026-05-21T14:30:00Z"
}

Calls

Get a transcript

GET/calls/{id}/transcript

Returns the call's transcript and AI-generated summary, or just one of them.

Both fields are populated asynchronously once the call ends, so a 200 carrying transcript: null indicates the transcript is not yet available for that call. Waiting for the call.recorded event before fetching is more efficient than polling.

summary also appears on the call object; it is repeated here so one request returns both halves of the post-call content. Transcripts can be long: when the summary may be enough, ask for part=summary first. With part=summary or part=transcript the response carries only that key — the other is absent, not null.

A heavy read for signed-in users; an ordinary read for API keys.

Path parameters
ParameterTypeDescription
idstring (uuid)reqThe call's unique identifier.
Query parameters
ParameterTypeDescription
partstringoptWhich half to return: summary, transcript, or both. Defaults to both. One of: summary, transcript, both.
Responses
200OK — a Transcript.
400id was not a UUID, or part was not one of summary, transcript, both — INVALID_REQUEST.
401Credential missing, malformed, revoked, or expired — INVALID_API_KEY.
403The signed-in user's role cannot use the API, or they are not on an active team — FORBIDDEN.
404Call not found, or not on this team — NOT_FOUND.
429Over a rate limit — RATE_LIMITED, with Retry-After.
500Failed to fetch transcript — SERVER_ERROR.
Response shape
{
  "transcript": "Agent: Hi Dana, this is…",
  "summary": "Prospect asked for pricing on the multi-line plan."
}

An inbound flow is what happens when someone calls one of the team's numbers: the ordered steps the call goes through. Each number group picks a flow, and the team default covers every number without one. These endpoints are available once the team has been moved onto inbound flows; until then they answer 403 with FORBIDDEN.

A flow's steps are stored as JSON and validated on save. The first step is always the callback step — it can be turned off but not removed. A flow that doesn't end in voicemail hangs up after its last step. Saving new steps writes a new version; calls already in progress finish on the version they started. Ids inside the steps (member groups, reps, greetings) are checked against the team when you save, and flagged on read if they have since been deleted (needsAttention, brokenLinks): a broken ring step is skipped at run time, so the call still reaches voicemail.

Inbound flows

List inbound flows

GET/inbound-flows

Returns every inbound flow on the team, the default first, each with its current steps, a one-sentence summary, which number groups use it, and whether it needs attention. defaultFlowId is the flow that numbers without a group flow run; it is null only for a team that has no flows yet.

Responses
200OK — a InboundFlowList.
401Credential missing, malformed, revoked, or expired — INVALID_API_KEY.
403The team is not on inbound flows, or the signed-in user's role cannot use the API — FORBIDDEN.
429Over a rate limit — RATE_LIMITED, with Retry-After.
500Failed to list flows — SERVER_ERROR.
Response shape
{
  "flows": [
    {
      "id": "0e8e7b7a-9a7a-4f0e-8a4e-0c5a4a5b6c7d",
      "name": "Sales line",
      "isDefault": false,
      "needsAttention": false,
      "routing": null,
      "brokenLinks": [
        {
          "stepId": "ring-sales",
          "stepType": "ringGroup",
          "kind": "memberGroup",
          "id": "6f1d2c3b-4a5e-4f60-8b7c-9d0e1f2a3b4c"
        }
      ],
      "summary": "Rings the rep who called them. If they can't answer, rings Sales team one at a time, then voicemail.",
      "version": 3,
      "steps": [
        {
          "id": "callback",
          "type": "callback",
          "enabled": true,
          "match": "anyTeamNumber",
          "ringSeconds": 20,
          "ifRepCantAnswer": "ringTeam"
        }
      ],
      "usedBy": {
        "numberGroups": [
          {
            "id": "2b7c1d9e-3f4a-4b5c-8d6e-7f8a9b0c1d2e",
            "name": "Support numbers",
            "numberCount": 4
          }
        ],
        "numberCount": 0,
        "ungroupedNumberCount": 12
      },
      "createdAt": "2026-11-04T16:20:00Z",
      "updatedAt": "2026-11-04T16:20:00Z"
    }
  ],
  "defaultFlowId": "0e8e7b7a-9a7a-4f0e-8a4e-0c5a4a5b6c7d"
}

Inbound flows

Create an inbound flow

POST/inbound-flows

Creates a flow as version 1. Leave steps out to start from the starter steps: the callback step on for any team number (moving on to the next step if that rep can't answer), then voicemail in the called-back rep's box, or the team's when the caller wasn't returning a call. A team that has not opened its flows yet gets them generated from its call forwarding settings first, and the generated one stays the team default; the flow you create never takes its place by itself.

The new flow is not used by anything until a number group picks it (in Group Settings) or you make it the default with PATCH … { "isDefault": true }.

Request body — InboundFlowCreate
FieldTypeDescription
namestringreq
stepsInboundFlowStep[]optThe steps, or leave out for the starter steps (callback on, then voicemail in the called-back rep's box, else the team's).
Responses
201Created — a InboundFlow.
400name missing or too long, steps not a valid flow (see InboundFlowStep), or a step points at a member group, rep or greeting that is not on the team — INVALID_REQUEST.
401Credential missing, malformed, revoked, or expired — INVALID_API_KEY.
403The team is not on inbound flows, or the signed-in user's role cannot use the API — FORBIDDEN.
429Over a rate limit — RATE_LIMITED, with Retry-After.
500Failed to create the flow, or to generate the team's flows first — SERVER_ERROR.
Request shape
{
  "name": "Sales line",
  "steps": [
    {
      "id": "callback",
      "type": "callback",
      "enabled": true,
      "match": "anyTeamNumber",
      "ringSeconds": 20,
      "ifRepCantAnswer": "ringTeam"
    },
    {
      "id": "ring-sales",
      "type": "ringGroup",
      "target": {
        "memberGroupIds": [
          "6f1d2c3b-4a5e-4f60-8b7c-9d0e1f2a3b4c"
        ]
      },
      "order": "roundRobin",
      "ringSeconds": 20
    },
    {
      "id": "voicemail",
      "type": "voicemail",
      "box": {
        "kind": "callbackRep"
      },
      "alert": {
        "kind": "callbackRepElseGroup"
      }
    }
  ]
}
Response shape
{
  "id": "0e8e7b7a-9a7a-4f0e-8a4e-0c5a4a5b6c7d",
  "name": "Sales line",
  "isDefault": false,
  "needsAttention": false,
  "routing": null,
  "brokenLinks": [
    {
      "stepId": "ring-sales",
      "stepType": "ringGroup",
      "kind": "memberGroup",
      "id": "6f1d2c3b-4a5e-4f60-8b7c-9d0e1f2a3b4c"
    }
  ],
  "summary": "Rings the rep who called them. If they can't answer, rings Sales team one at a time, then voicemail.",
  "version": 3,
  "steps": [
    {
      "id": "callback",
      "type": "callback",
      "enabled": true,
      "match": "anyTeamNumber",
      "ringSeconds": 20,
      "ifRepCantAnswer": "ringTeam"
    }
  ],
  "usedBy": {
    "numberGroups": [
      {
        "id": "2b7c1d9e-3f4a-4b5c-8d6e-7f8a9b0c1d2e",
        "name": "Support numbers",
        "numberCount": 4
      }
    ],
    "numberCount": 0,
    "ungroupedNumberCount": 12
  },
  "createdAt": "2026-11-04T16:20:00Z",
  "updatedAt": "2026-11-04T16:20:00Z"
}

Inbound flows

Get an inbound flow

GET/inbound-flows/{id}

Returns one flow with its current steps, summary and usage.

Path parameters
ParameterTypeDescription
idstring (uuid)reqThe flow's unique identifier.
Responses
200OK — a InboundFlow.
400id was not a UUID — INVALID_REQUEST.
401Credential missing, malformed, revoked, or expired — INVALID_API_KEY.
403The team is not on inbound flows, or the signed-in user's role cannot use the API — FORBIDDEN.
404Flow not found, deleted, or not on this team — NOT_FOUND.
429Over a rate limit — RATE_LIMITED, with Retry-After.
500Failed to fetch the flow — SERVER_ERROR.
Response shape
{
  "id": "0e8e7b7a-9a7a-4f0e-8a4e-0c5a4a5b6c7d",
  "name": "Sales line",
  "isDefault": false,
  "needsAttention": false,
  "routing": null,
  "brokenLinks": [
    {
      "stepId": "ring-sales",
      "stepType": "ringGroup",
      "kind": "memberGroup",
      "id": "6f1d2c3b-4a5e-4f60-8b7c-9d0e1f2a3b4c"
    }
  ],
  "summary": "Rings the rep who called them. If they can't answer, rings Sales team one at a time, then voicemail.",
  "version": 3,
  "steps": [
    {
      "id": "callback",
      "type": "callback",
      "enabled": true,
      "match": "anyTeamNumber",
      "ringSeconds": 20,
      "ifRepCantAnswer": "ringTeam"
    }
  ],
  "usedBy": {
    "numberGroups": [
      {
        "id": "2b7c1d9e-3f4a-4b5c-8d6e-7f8a9b0c1d2e",
        "name": "Support numbers",
        "numberCount": 4
      }
    ],
    "numberCount": 0,
    "ungroupedNumberCount": 12
  },
  "createdAt": "2026-11-04T16:20:00Z",
  "updatedAt": "2026-11-04T16:20:00Z"
}

Inbound flows

Update an inbound flow

PATCH/inbound-flows/{id}

Renames a flow, saves a new version of its steps, or makes it the team default — any combination; at least one of name, steps, isDefault is required. New steps replace the whole list and become the next version; a rename alone writes no version. Send baseVersion (the version you read) with new steps and they are refused when another save moved the flow on since, so two editors can't overwrite each other: read the flow again and resave. Without baseVersion, only a save racing this one is refused.

isDefault only accepts true. To stop a flow being the default, make another flow the default instead, so the team is never without one.

Path parameters
ParameterTypeDescription
idstring (uuid)reqThe flow's unique identifier.
Request body — InboundFlowPatch
FieldTypeDescription
namestringopt
stepsInboundFlowStep[]optReplaces the whole list and becomes the next version.
baseVersionintegeroptThe version the new steps were built from. If the flow has moved past it, the save is refused with 409. Ignored without steps.
isDefaultbooleanoptMake this flow the team default.
Responses
200The flow after the change. — a InboundFlow.
400Nothing to change, isDefault was not true, baseVersion not a positive integer, steps not a valid flow, a step points outside the team, or a forwardTo number is not verified — INVALID_REQUEST.
401Credential missing, malformed, revoked, or expired — INVALID_API_KEY.
403The team is not on inbound flows, or the signed-in user's role cannot use the API — FORBIDDEN.
404Flow not found, deleted, or not on this team — NOT_FOUND.
409The flow's version is no longer baseVersion, or another save of new steps landed at the same moment — CONFLICT. Read it again and resave.
429Over a rate limit — RATE_LIMITED, with Retry-After.
500Failed to update the flow — SERVER_ERROR.
Request shape
{
  "name": "Sales line (after hours)",
  "isDefault": true
}
Response shape
{
  "id": "0e8e7b7a-9a7a-4f0e-8a4e-0c5a4a5b6c7d",
  "name": "Sales line",
  "isDefault": false,
  "needsAttention": false,
  "routing": null,
  "brokenLinks": [
    {
      "stepId": "ring-sales",
      "stepType": "ringGroup",
      "kind": "memberGroup",
      "id": "6f1d2c3b-4a5e-4f60-8b7c-9d0e1f2a3b4c"
    }
  ],
  "summary": "Rings the rep who called them. If they can't answer, rings Sales team one at a time, then voicemail.",
  "version": 3,
  "steps": [
    {
      "id": "callback",
      "type": "callback",
      "enabled": true,
      "match": "anyTeamNumber",
      "ringSeconds": 20,
      "ifRepCantAnswer": "ringTeam"
    }
  ],
  "usedBy": {
    "numberGroups": [
      {
        "id": "2b7c1d9e-3f4a-4b5c-8d6e-7f8a9b0c1d2e",
        "name": "Support numbers",
        "numberCount": 4
      }
    ],
    "numberCount": 0,
    "ungroupedNumberCount": 12
  },
  "createdAt": "2026-11-04T16:20:00Z",
  "updatedAt": "2026-11-04T16:20:00Z"
}

Inbound flows

Delete an inbound flow

DELETE/inbound-flows/{id}

Deletes a flow. Refused while it is the team default or a number group still uses it (409): make another flow the default, or move the group to another flow, then retry. Ungrouped numbers that pointed at the flow directly move to the team default.

Path parameters
ParameterTypeDescription
idstring (uuid)reqThe flow's unique identifier.
Responses
200Deleted.
400id was not a UUID — INVALID_REQUEST.
401Credential missing, malformed, revoked, or expired — INVALID_API_KEY.
403The team is not on inbound flows, or the signed-in user's role cannot use the API — FORBIDDEN.
404Flow not found, already deleted, or not on this team — NOT_FOUND.
409The flow is the team default, or a number group uses it — CONFLICT.
429Over a rate limit — RATE_LIMITED, with Retry-After.
500Failed to delete the flow — SERVER_ERROR.
Response shape
{
  "deleted": true
}

Inbound flows

Routing webhook (Ask your system)

EVENTinbound.route

Not an event you subscribe to: a question WAVV asks while the caller is still hearing ringing, and your reply decides where the call goes. It is sent by a webhook step ("Ask your system") in an inbound flow, to the one endpoint the team set under Integrations › Inbound Routing.

  • Always answer 200 with a JSON action. To leave the call alone, reply {"action":"continue"}. Anything else (no reply within 5 seconds, a non-2xx status, a redirect, an empty body or 204, or a body that isn't one of the actions below) sends the call to the flow's next step and counts as a failure (see the pause below). A call is never dropped because your system was slow or down.
  • Signed like every WAVV webhook, with its own secret. Verify X-WAVV-Signature (t=<unix seconds>,v1=<hmac>) as in Verifying signatures, using the whsec_ secret shown on the Inbound Routing page. It is separate from your other webhooks' secrets, one per team, and doesn't change. Worked example: with secret whsec_test_secret, t=1779720600 and the raw body {"event":"inbound.route","test":true}, v1 is 0adcc2ab3090e6bffbc10ca16d62caa27c9cdc578ac9c8de42bae3bb15f242a2. The request also carries X-WAVV-Event: inbound.route and User-Agent: WAVV-Inbound-Routing/1.
  • Mostly you reply goto. Build each path in the flow editor (for example "best reps, then the whole team" and "the whole team only"), give the first step of each path a key, and reply with the key. The flow carries on down the list from the step you name. stepKeys in the request lists the keys you can use; only steps after the asking step can be jumped to.
  • After 5 failures in 5 minutes WAVV stops asking for 5 minutes, alerts the team's admins once per outage, and marks the flows that ask as needing attention. Calls skip the step meanwhile. A reply WAVV understands but can't use (an unknown goto key, an unknown rep, a number it won't forward to) goes to the next step without counting as a failure.
  • One request per call, never retried. Use callId to log and dedupe. If the caller hangs up while WAVV is waiting, the call ends as missed and your reply is ignored.
  • The endpoint must resolve to a public address; redirects aren't followed, and replies over 64 KB are refused. Unknown fields in your reply are ignored, and action is case-sensitive.
  • Send test from the settings page carries test: true and placeholder values (callId test-call, sample numbers, contact, callback and forwardedFrom null). Nothing is routed and it never counts as a failure, so reply as you would to a real call but skip side effects.
FieldTypeDescription
eventstringreq
testbooleanreqTrue for a Send test from the settings page. Nothing is routed and nobody's phone rings.
callIdstringreqThe inbound call's id. Stable for the whole call, so use it to log and dedupe. It isn't guaranteed to match the call's id in /calls and call events.
flowobjectreq
stepobjectreqThe step that is asking.
fromstringreqThe caller.
tostringreqThe WAVV number they dialed.
forwardedFromstring | nullreqThe outside line that forwarded the call to to, when the carrier says so (the SIP Diversion header). null means not known, not "not forwarded".
contactobject | nullreqThe caller's contact in WAVV, when the number matches one. crmId is the id in your CRM.
callbackobject | nullreqThe rep who last called this caller, when the flow's callback step matched one.
availableRepsobject[]reqThe team's reps who could take the call right now: Available, connected, and not on a call. Use it to pick a free rep without a separate status lookup; match them to your own users by email.
stepKeysstring[]reqThe keys a goto reply can name — the keyed steps after the asking step. goto also accepts a step's id.
Your endpoint should return
200Where the call goes. A worked example: the flow has an Ask step, then a ringGroup step keyed best-reps (15 seconds), then one keyed whole-team (30 seconds), then voicemail. For a lead worth your best reps reply {"action":"goto","step":"best-reps"}: the best reps ring, then the whole team (with the best reps still ringing), then voicemail. For everyone else reply {"action":"goto","step":"whole-team"}: the whole team rings, then voicemail. — a InboundRoutingReply.
Example delivery
{
  "event": "inbound.route",
  "test": false,
  "callId": "9a1c7b52-0d3e-4f8a-b6c1-2e4d6f8a0b1c",
  "flow": {
    "id": "0e8e7b7a-9a7a-4f0e-8a4e-0c5a4a5b6c7d",
    "name": "Sales line"
  },
  "step": {
    "id": "ask",
    "key": null
  },
  "from": "+13855550187",
  "to": "+18015550142",
  "forwardedFrom": "+18015550100",
  "contact": {
    "id": "5d1e8a72-9c34-4f60-8b2a-7e0d3c5f9b18",
    "crmId": "crm-99213",
    "name": "Dana Reyes"
  },
  "callback": {
    "repId": "usr_8f3b2c10",
    "calledAt": "2026-05-21T14:28:12Z"
  },
  "availableReps": [
    {
      "id": "usr_2a9d4e71",
      "email": "jake@summitrealty.com",
      "name": "Jake Morris"
    },
    {
      "id": "usr_77c0b1f3",
      "email": "maria@summitrealty.com",
      "name": "Maria Lopez"
    }
  ],
  "stepKeys": [
    "best-reps",
    "whole-team",
    "voicemail"
  ]
}

Five events cover the life of a call. Every payload uses the same envelope — event, sentAt, and a data object holding the Call — so one handler can serve all five and branch on event.

Call events

Outbound call started

EVENTcall.started

Fires the moment an outbound call is created — when the dialer places it, before the far end has answered or rejected.

Because the call has only just begun, endedAt, seconds, answeredAt, disposition, human, note, and summary are null, and outcome is UNKNOWN. Use this event to open a record that call.ended will complete; call results are not available until then.

Payload — CallEvent
FieldTypeDescription
eventstringreqWhich event fired. Branch your handler on this. One of: call.started, call.incoming, call.answered, call.ended, call.recorded, call.missed.
sentAtstring (date-time)reqWhen this payload was rendered. It is set once when the event is dispatched, so retries of the same delivery carry the original value. Use the t parameter in X-WAVV-Signature for freshness and replay checks.
dataCallreqThe canonical call shape. Identical in REST responses and webhook payloads. transcript is not part of it; fetch it from GET /calls/{id}/transcript, or list calls with includeTranscripts=true, which returns CallWithTranscript. Webhooks never carry it.
Your endpoint should return
2XXAny 2xx acknowledges the delivery. Anything else is retried.
Example delivery
{
  "event": "call.started",
  "sentAt": "2026-05-21T14:28:12Z",
  "data": {
    "id": "3c9a17b4-2f5e-4d81-b0a7-6e2c9d4f1a03",
    "teamId": "8f3b2c10-4e7a-4b1c-9d2e-1a2b3c4d5e6f",
    "userId": "crm-user-4471",
    "groupId": "west-region",
    "subgroupId": "team-4",
    "campaignId": "5d1e8a72-9c34-4f60-8b2a-7e0d3c5f9b18",
    "direction": "outbound",
    "phone": "5125551234",
    "callerId": "5125559876",
    "contactId": "crm-99213",
    "contactName": "Dana Reyes",
    "startedAt": "2026-05-21T14:28:12Z",
    "answeredAt": null,
    "endedAt": null,
    "seconds": null,
    "outcome": "UNKNOWN",
    "disposition": null,
    "human": null,
    "note": null,
    "summary": null,
    "recorded": false
  }
}

Call events

Inbound call received

EVENTcall.incoming

Fires when an inbound call arrives on one of the team's numbers, at the point the call record is created — before it is answered, routed, or forwarded.

The counterpart to call.started for the inbound direction, with the same fields still unpopulated. phone and callerId follow the call rather than the account, so here phone is your WAVV number that was dialed and callerId is the caller's number. campaignId and contactId are null unless the caller matches a known CRM contact.

Payload — CallEvent
FieldTypeDescription
eventstringreqWhich event fired. Branch your handler on this. One of: call.started, call.incoming, call.answered, call.ended, call.recorded, call.missed.
sentAtstring (date-time)reqWhen this payload was rendered. It is set once when the event is dispatched, so retries of the same delivery carry the original value. Use the t parameter in X-WAVV-Signature for freshness and replay checks.
dataCallreqThe canonical call shape. Identical in REST responses and webhook payloads. transcript is not part of it; fetch it from GET /calls/{id}/transcript, or list calls with includeTranscripts=true, which returns CallWithTranscript. Webhooks never carry it.
Your endpoint should return
2XXAny 2xx acknowledges the delivery. Anything else is retried.
Example delivery
{
  "event": "call.incoming",
  "sentAt": "2026-05-21T16:02:44Z",
  "data": {
    "id": "b7e4d290-13af-4c65-9a08-fd2e6b510c77",
    "teamId": "8f3b2c10-4e7a-4b1c-9d2e-1a2b3c4d5e6f",
    "userId": "crm-user-4471",
    "groupId": "west-region",
    "subgroupId": "team-4",
    "campaignId": null,
    "direction": "inbound",
    "phone": "5125559876",
    "callerId": "5125551234",
    "contactId": null,
    "contactName": null,
    "startedAt": "2026-05-21T16:02:44Z",
    "answeredAt": null,
    "endedAt": null,
    "seconds": null,
    "outcome": "UNKNOWN",
    "disposition": null,
    "human": null,
    "note": null,
    "summary": null,
    "recorded": false
  }
}

Call events

Call answered

EVENTcall.answered

Fires when a call connects to the agent — an outbound call the contact picked up, or an inbound call the agent took. It fires once per call: putting the call on hold or transferring it does not fire it again.

Calls that never connect never fire it. Neither does a voicemail that answering-machine detection screens out before it reaches the agent. A voicemail that does reach the agent fires it like any other answer, so check human on call.ended before treating the call as a conversation.

answeredAt is populated with the moment the call connected. As on call.started, the call is still live, so endedAt, seconds, disposition, human, note, and summary are null, and outcome is UNKNOWN.

Payload — CallEvent
FieldTypeDescription
eventstringreqWhich event fired. Branch your handler on this. One of: call.started, call.incoming, call.answered, call.ended, call.recorded, call.missed.
sentAtstring (date-time)reqWhen this payload was rendered. It is set once when the event is dispatched, so retries of the same delivery carry the original value. Use the t parameter in X-WAVV-Signature for freshness and replay checks.
dataCallreqThe canonical call shape. Identical in REST responses and webhook payloads. transcript is not part of it; fetch it from GET /calls/{id}/transcript, or list calls with includeTranscripts=true, which returns CallWithTranscript. Webhooks never carry it.
Your endpoint should return
2XXAny 2xx acknowledges the delivery. Anything else is retried.
Example delivery
{
  "event": "call.answered",
  "sentAt": "2026-05-21T14:28:21Z",
  "data": {
    "id": "3c9a17b4-2f5e-4d81-b0a7-6e2c9d4f1a03",
    "teamId": "8f3b2c10-4e7a-4b1c-9d2e-1a2b3c4d5e6f",
    "userId": "crm-user-4471",
    "groupId": "west-region",
    "subgroupId": "team-4",
    "campaignId": "5d1e8a72-9c34-4f60-8b2a-7e0d3c5f9b18",
    "direction": "outbound",
    "phone": "5125551234",
    "callerId": "5125559876",
    "contactId": "crm-99213",
    "contactName": "Dana Reyes",
    "startedAt": "2026-05-21T14:28:12Z",
    "answeredAt": "2026-05-21T14:28:19Z",
    "endedAt": null,
    "seconds": null,
    "outcome": "UNKNOWN",
    "disposition": null,
    "human": null,
    "note": null,
    "summary": null,
    "recorded": false
  }
}

Call events

Call ended and dispositioned

EVENTcall.ended

Fires when the call is over and its outcome has been recorded. This is the complete call: endedAt, seconds, answeredAt, outcome, human, and any disposition or note the agent entered are all populated.

For most integrations this is the only event you need. It fires for both directions.

Two fields may still be null here and arrive later: summary (AI-generated) and any recording — see call.recorded.

Payload — CallEvent
FieldTypeDescription
eventstringreqWhich event fired. Branch your handler on this. One of: call.started, call.incoming, call.answered, call.ended, call.recorded, call.missed.
sentAtstring (date-time)reqWhen this payload was rendered. It is set once when the event is dispatched, so retries of the same delivery carry the original value. Use the t parameter in X-WAVV-Signature for freshness and replay checks.
dataCallreqThe canonical call shape. Identical in REST responses and webhook payloads. transcript is not part of it; fetch it from GET /calls/{id}/transcript, or list calls with includeTranscripts=true, which returns CallWithTranscript. Webhooks never carry it.
Your endpoint should return
2XXAny 2xx acknowledges the delivery. Anything else is retried.
Example delivery
{
  "event": "call.ended",
  "sentAt": "2026-05-21T14:30:01Z",
  "data": {
    "id": "3c9a17b4-2f5e-4d81-b0a7-6e2c9d4f1a03",
    "teamId": "8f3b2c10-4e7a-4b1c-9d2e-1a2b3c4d5e6f",
    "userId": "crm-user-4471",
    "groupId": "west-region",
    "subgroupId": "team-4",
    "campaignId": "5d1e8a72-9c34-4f60-8b2a-7e0d3c5f9b18",
    "direction": "outbound",
    "phone": "5125551234",
    "callerId": "5125559876",
    "contactId": "crm-99213",
    "contactName": "Dana Reyes",
    "startedAt": "2026-05-21T14:28:12Z",
    "answeredAt": "2026-05-21T14:28:19Z",
    "endedAt": "2026-05-21T14:30:00Z",
    "seconds": 101,
    "outcome": "HUNG_UP",
    "disposition": "Interested",
    "human": true,
    "note": "Sending pricing.",
    "summary": null,
    "recorded": true
  }
}

Call events

Inbound call missed

EVENTcall.missed

Fires when an inbound call ends with nobody on the team answering it: the caller hung up while it rang, the flow ran out of reps to try, or the caller went to voicemail. Only teams routed by inbound flows send it; an inbound call answered by an agent never does.

It arrives about ten seconds after the call ends, with endedAt set, answeredAt null, seconds 0 and outcome either NO_ANSWER or VOICEMAIL. A VOICEMAIL outcome means the caller reached a voicemail box; the recording itself is not part of this event. The same call also sends call.ended, so subscribe to one or the other: call.missed when you only want to react to missed calls (a text-back, a task for the rep), call.ended when you log every call. As with all events, order is not guaranteed — see Delivery and retries.

Payload — CallEvent
FieldTypeDescription
eventstringreqWhich event fired. Branch your handler on this. One of: call.started, call.incoming, call.answered, call.ended, call.recorded, call.missed.
sentAtstring (date-time)reqWhen this payload was rendered. It is set once when the event is dispatched, so retries of the same delivery carry the original value. Use the t parameter in X-WAVV-Signature for freshness and replay checks.
dataCallreqThe canonical call shape. Identical in REST responses and webhook payloads. transcript is not part of it; fetch it from GET /calls/{id}/transcript, or list calls with includeTranscripts=true, which returns CallWithTranscript. Webhooks never carry it.
Your endpoint should return
2XXAny 2xx acknowledges the delivery. Anything else is retried.
Example delivery
{
  "event": "call.missed",
  "sentAt": "2026-05-21T16:03:40Z",
  "data": {
    "id": "b7e4d290-13af-4c65-9a08-fd2e6b510c77",
    "teamId": "8f3b2c10-4e7a-4b1c-9d2e-1a2b3c4d5e6f",
    "userId": "crm-user-4471",
    "groupId": "west-region",
    "subgroupId": "team-4",
    "campaignId": null,
    "direction": "inbound",
    "phone": "5125559876",
    "callerId": "5125551234",
    "contactId": "crm-99213",
    "contactName": "Dana Reyes",
    "startedAt": "2026-05-21T16:02:44Z",
    "answeredAt": null,
    "endedAt": "2026-05-21T16:03:29Z",
    "seconds": 0,
    "outcome": "NO_ANSWER",
    "disposition": null,
    "human": null,
    "note": null,
    "summary": null,
    "recorded": false
  }
}

Call events

Recording available

EVENTcall.recorded

Fires when a call's audio recording has finished processing and is available.

This is the only event whose data carries an extra field: recordingUrl, a signed URL for the audio. The URL is generated at send time and is time-limited, so download the audio when you receive it, or request a fresh URL from GET /calls/{id}/recording later. Store the call id rather than the URL.

This event typically follows call.ended within seconds. As with all events, order is not guaranteed — see Delivery and retries.

Payload — CallRecordedEvent
FieldTypeDescription
eventstringreqAlways call.recorded.
sentAtstring (date-time)reqWhen this payload was rendered.
dataCallWithRecordingreqA Call plus the signed recording URL. Used only as the data of a call.recorded event.
Your endpoint should return
2XXAny 2xx acknowledges the delivery. Anything else is retried.
Example delivery
{
  "event": "call.recorded",
  "sentAt": "2026-05-21T14:30:14Z",
  "data": {
    "id": "3c9a17b4-2f5e-4d81-b0a7-6e2c9d4f1a03",
    "teamId": "8f3b2c10-4e7a-4b1c-9d2e-1a2b3c4d5e6f",
    "userId": "crm-user-4471",
    "groupId": "west-region",
    "subgroupId": "team-4",
    "campaignId": "5d1e8a72-9c34-4f60-8b2a-7e0d3c5f9b18",
    "direction": "outbound",
    "phone": "5125551234",
    "callerId": "5125559876",
    "contactId": "crm-99213",
    "contactName": "Dana Reyes",
    "startedAt": "2026-05-21T14:28:12Z",
    "answeredAt": "2026-05-21T14:28:19Z",
    "endedAt": "2026-05-21T14:30:00Z",
    "seconds": 101,
    "outcome": "HUNG_UP",
    "disposition": "Interested",
    "human": true,
    "note": "Sending pricing.",
    "summary": "Prospect asked for pricing on the multi-line plan.",
    "recorded": true,
    "recordingUrl": "https://recordings.wavv.com/3c9a17b4…?X-Amz-Expires=259200&X-Amz-Signature=…"
  }
}

Three events follow a text message: sent, received, and failed. The envelope matches the call events — event, sentAt, and a data object — with a Message in data, so the same handler and the same signature check serve both.

Message events

Text message sent

EVENTmessage.sent

Fires once when the carrier accepts an outbound text — sent, not yet delivered. A message the carrier later reports as undelivered follows with message.failed, so a message can fire both.

Scheduled messages fire when they actually go out, not when they are scheduled.

Payload — MessageEvent
FieldTypeDescription
eventstringreqWhich event fired. Branch your handler on this. One of: message.sent, message.received, message.failed.
sentAtstring (date-time)reqWhen this payload was rendered. Retries of the same delivery carry the original value.
dataMessagereqA text message, as delivered in every message.* webhook. Like the Call, its ids are yours: userId is the id you passed to POST /tokens, and contactId is your contact id.
Your endpoint should return
2XXAny 2xx acknowledges the delivery. Anything else is retried.
Example delivery
{
  "event": "message.sent",
  "sentAt": "2026-05-21T14:31:03Z",
  "data": {
    "id": "0b6f2d1e-8a4c-4e3b-9f71-2c5d8e1a4b90",
    "teamId": "8f3b2c10-4e7a-4b1c-9d2e-1a2b3c4d5e6f",
    "userId": "crm-user-4471",
    "conversationId": "6a2e9c47-1d3b-4f58-a0e6-93b7c5d21f84",
    "direction": "outbound",
    "userNumber": "5125559876",
    "contactNumber": "5125551234",
    "contactId": "crm-99213",
    "body": "Thanks for your time today — here is the pricing sheet.",
    "attachments": [],
    "segments": 1,
    "status": "sent",
    "failedReason": null,
    "createdAt": "2026-05-21T14:31:02Z",
    "sentAt": "2026-05-21T14:31:03Z",
    "failedAt": null
  }
}

Message events

Text message received

EVENTmessage.received

Fires when a contact texts one of your users' WAVV numbers.

userId is the user whose conversation it landed in. On a number the whole team shares there is no single owner, so userId is null; use teamId and conversationId to place the message.

Payload — MessageEvent
FieldTypeDescription
eventstringreqWhich event fired. Branch your handler on this. One of: message.sent, message.received, message.failed.
sentAtstring (date-time)reqWhen this payload was rendered. Retries of the same delivery carry the original value.
dataMessagereqA text message, as delivered in every message.* webhook. Like the Call, its ids are yours: userId is the id you passed to POST /tokens, and contactId is your contact id.
Your endpoint should return
2XXAny 2xx acknowledges the delivery. Anything else is retried.
Example delivery
{
  "event": "message.received",
  "sentAt": "2026-05-21T14:40:17Z",
  "data": {
    "id": "4d1c7e93-2b6a-4f0e-8c35-a9e2f7b16d08",
    "teamId": "8f3b2c10-4e7a-4b1c-9d2e-1a2b3c4d5e6f",
    "userId": "crm-user-4471",
    "conversationId": "6a2e9c47-1d3b-4f58-a0e6-93b7c5d21f84",
    "direction": "inbound",
    "userNumber": "5125559876",
    "contactNumber": "5125551234",
    "contactId": "crm-99213",
    "body": "Got it, thanks. Can we talk Thursday?",
    "attachments": [],
    "segments": 1,
    "status": "received",
    "failedReason": null,
    "createdAt": "2026-05-21T14:40:16Z",
    "sentAt": "2026-05-21T14:40:16Z",
    "failedAt": null
  }
}

Message events

Text message failed

EVENTmessage.failed

Fires once when an outbound text fails — rejected before it left WAVV (for example, the number is on a do-not-contact list), refused by the carrier, or reported undelivered after it was sent. failedReason says why, in words you can show the user.

A message the carrier accepted and later reported undelivered has already fired message.sent, so treat message.failed as overriding it rather than as a message that was never sent.

Payload — MessageEvent
FieldTypeDescription
eventstringreqWhich event fired. Branch your handler on this. One of: message.sent, message.received, message.failed.
sentAtstring (date-time)reqWhen this payload was rendered. Retries of the same delivery carry the original value.
dataMessagereqA text message, as delivered in every message.* webhook. Like the Call, its ids are yours: userId is the id you passed to POST /tokens, and contactId is your contact id.
Your endpoint should return
2XXAny 2xx acknowledges the delivery. Anything else is retried.
Example delivery
{
  "event": "message.failed",
  "sentAt": "2026-05-21T14:31:09Z",
  "data": {
    "id": "0b6f2d1e-8a4c-4e3b-9f71-2c5d8e1a4b90",
    "teamId": "8f3b2c10-4e7a-4b1c-9d2e-1a2b3c4d5e6f",
    "userId": "crm-user-4471",
    "conversationId": "6a2e9c47-1d3b-4f58-a0e6-93b7c5d21f84",
    "direction": "outbound",
    "userNumber": "5125559876",
    "contactNumber": "5125551234",
    "contactId": "crm-99213",
    "body": "Thanks for your time today — here is the pricing sheet.",
    "attachments": [],
    "segments": 1,
    "status": "failed",
    "failedReason": "The carrier could not deliver this message to the recipient.",
    "createdAt": "2026-05-21T14:31:02Z",
    "sentAt": "2026-05-21T14:31:03Z",
    "failedAt": "2026-05-21T14:31:08Z"
  }
}

MCP

MCP server

WAVV runs a Model Context Protocol server, so an AI assistant such as Claude or ChatGPT can work with your team's calls and call boards directly: "how many conversations did we have yesterday", "why did this lead leave the Follow up stage", "get a calling session ready for everyone in Follow up".

https://app.wavv.com/api/v3/mcp

The server speaks Streamable HTTP and is stateless: every request is a POST that stands on its own, with no session to keep. GET and DELETE answer 405.

Connecting

Claude. Open Customize → Connectors, click +, choose Add custom connector, and paste the URL above. Click Connect, sign in with WAVV, pick the WAVV account to connect if you have more than one, and choose Allow.

ChatGPT. Go to chatgpt.com/plugins, click +, choose Add custom MCP server, paste the URL above, choose OAuth, and sign in with WAVV when asked.

Cursor or VS Code. Add the URL above as an HTTP server — in Cursor, an entry in mcp.json with "url"; in VS Code, MCP: Add Server → HTTP — and sign in with WAVV when the editor asks.

With an API key. Clients that let you set headers, such as Claude Code, can connect with an API key instead of signing in:

claude mcp add --transport http wavv https://app.wavv.com/api/v3/mcp --header "Authorization: Bearer <key>"

What the assistant can do

That depends on how it connected:

  • Signed in with WAVV — every tool below. The assistant acts as the person who signed in: it sees only the boards and contacts they see in WAVV, and can change only what they could change there. The reports are the exception: like the Reports page, they cover the whole team. Only owners, admins, and managers can connect this way.
  • API key — the call tools, get_me, and get_call_report. A key belongs to the team rather than a person, so the call board and calling tools are not offered.

Who is connected. get_me returns the team and, for someone signed in, the person: their role, their id in your CRM (pass it as userId for "my calls"), their time zone, and the WAVV tabs they have open. Assistants call it first.

Calls. Each mirrors a REST endpoint and takes the same parameters:

Call report. get_call_report returns one section of the call report on WAVV's Reports page, with the same numbers the page shows, for the team or one agent and optionally one call board: activity per agent and per day, week, or month; totals per agent; or a heatmap of dispositions by weekday and hour. Assistants use it for "how many calls did we make yesterday" rather than paging through calls. Like the page, it goes back to the 1st of the month a year ago; an earlier start is moved up to that day. The report is team-wide: it covers every agent on the team, whoever is asking.

Call boards (signed in only):

  • list_boards — the boards the person can open.
  • get_board — a board's setup: stages, automations written out as rules, calling settings (including the stage ids its Call button dials), where its contacts come from, and its members.
  • list_stage_contacts — the contacts in one stage, in dialing order, with attempts, time in stage, and who they're assigned to.
  • test_board_trigger — dry-runs a trigger on a board without changing any contacts or calling your CRM, returning which rules matched, how each condition evaluated, which actions applied or were overridden, and the contact's state before and after. It also runs the follow-on triggers a real run fires, in the order live runs them: a stage move's or board move's ENTERED_STAGE rules (on the board the contact lands on) and a scheduled call's CALL_SCHEDULED rules, up to 10 follow-on runs. A call that books a callback runs the board's CALL_SCHEDULED rules first, as live does. Triggers that come back later through your CRM or a sent text are listed but not run.
  • find_board_contacts — finds contacts on a board by name or phone, or by their contact ids in your CRM. Looked up by CRM id, each contact comes back with its stage and calling state (snooze, scheduled call, do-not-call), or as no longer on the board.
  • get_contact_trail — a contact's history on a board: stage moves, calls, and the rules that moved them.
  • get_automation_run — what one automation run did.
  • get_board_calls — a board's calls over a window of time, and whether each contact moved stage or an automation ran afterwards.
  • get_board_activity — everything that happened on a board over a window of time.
  • get_board_import_history and get_board_automation_history — contacts added to a board, and changes to its rules.
  • get_board_report — one section of the Call Boards report, with the same numbers as WAVV's Reports page. Like the page, it is team-wide: it covers every active board on the team, including boards the person signed in can't open.

The board tools name people the way calls do: userId is the person's user id in your CRM (null if they have none), and wavvUserId is WAVV's own id for them. A board member from get_board can be passed as either to filter get_board_report or to assign contacts.

Changing a board (signed in only):

  • preview_import, import_to_board, get_import_status — add contacts from your CRM to a board.
  • preview_bulk_action, run_bulk_action, get_bulk_action_status — act on many contacts at once, such as moving, assigning, snoozing, or removing them, or moving them to another board.

Both always go in two steps. The preview says exactly what will happen, to how many contacts, and changes nothing. The change runs only with that preview's confirm token, which works once and expires after 10 minutes, so the assistant has to show the preview and get a yes first.

Calling (signed in only):

  • prepare_campaign — gets a calling session ready, on a call board or for a list of CRM contacts. It appears in the person's open WAVV tab, and they press Start.

The assistant never dials. import_to_board, run_bulk_action, and prepare_campaign are marked as changing something, so clients ask before running them.

Feedback (signed in only):

  • submit_feedback — sends the WAVV team a feature request, bug report, or other feedback. When someone asks for something the tools can't do, the assistant offers to send it, and sends it only if they say yes.

Prompts

Ready-made requests a person picks from their assistant's prompt menu (/ in Claude):

  • review_yesterdays_calls — totals, standout calls, and follow-ups from yesterday.
  • score_calls_against_script — grades recent conversations against a script you give it. Arguments: script, and days to look back (default 7).
  • who_should_i_call_next — suggests which call board leads to work next, and why. Signed in only.
  • clean_up_a_board — finds contacts on a board that look stuck or over-called and suggests what to do with each group, previewing any change before it runs. Argument: board, the board's name. Signed in only.

Responses, errors, and limits

A tool returns JSON, as text; the call tools return the same JSON as their endpoints. A failure comes back as a tool error carrying the same message the REST error field would. Tool calls count against the same rate limits as REST requests. The call report, the board report, the board calls and activity reads, both previews, and a calling session for a list of CRM contacts are heavy reads.

OAuth discovery

You only need this if you are writing an MCP client. A request without a valid credential gets 401 with a challenge pointing at the server's protected-resource metadata (RFC 9728), which names WAVV's authorization server:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://app.wavv.com/api/v3/mcp/.well-known/oauth-protected-resource", scope="mcp"

The metadata is also served at the RFC 9728 well-known path, https://app.wavv.com/.well-known/oauth-protected-resource/api/v3/mcp. Tokens are issued for the resource https://app.wavv.com/api/v3/mcp with the mcp scope.

Reference

Object reference

The shape of every object the API returns or accepts. A field marked req is always present in a response (or required in a request body). Types ending in | null may come back as null.

Call

The canonical call shape. Identical in REST responses and webhook payloads. transcript is not part of it; fetch it from GET /calls/{id}/transcript, or list calls with includeTranscripts=true, which returns CallWithTranscript. Webhooks never carry it.

FieldTypeDescription
idstring (uuid)reqThe call's unique identifier. Stable; safe to store and use as your dedupe key.
teamIdstring (uuid)reqThe team the call belongs to. Always the team your credential is scoped to.
userIdstringreqThe agent who made or received the call, in your identifier space — the same id you supplied when provisioning the user, not a WAVV-internal one. Never null.
groupIdstring | nullreqYour grouping for the agent, if you set one when provisioning them. null when the account does not use groups.
subgroupIdstring | nullreqYour second-level grouping, if you set one. null when unused.
campaignIdstring (uuid) | nullreqThe dialing campaign this call was placed under. null for inbound and ad-hoc calls.
directionstringreqinbound covers calls received on a team number, including forwarded ones. Everything else — dialer-placed calls, and internal types such as whispers and transfers — reports as outbound. The direction filter on GET /calls is narrower: its outbound returns only dialer-placed calls, so the internal types are never listed. One of: inbound, outbound.
phonestringreqThe number that was called. On outbound that is the contact you dialed; on inbound it is your own WAVV number that the caller reached. Unformatted 10 digits.
callerIdstringreqThe number the call came from. On outbound that is the WAVV caller ID you presented; on inbound it is the external caller's number. Unformatted 10 digits. Because phone and callerId follow the call rather than the account, read direction first to determine which of the two identifies your contact.
contactIdstring | nullreqThe contact's id in the connected CRM, when the call was placed against a known contact. null for manual dials and unmatched inbound calls.
contactNamestring | nullreqThe contact's display name at the time of the call. null when unknown.
startedAtstring (date-time)reqWhen the call was created — dialed, or received. Also the sort key and pagination cursor.
answeredAtstring (date-time) | nullreqWhen the call connected, derived as endedAt - seconds. null until both of those are known, and for calls that were never answered. On call.answered it is instead the moment the call connected, since the call has not ended yet; the derived value on later events can differ from it by a second or two.
endedAtstring (date-time) | nullreqWhen the call finished. null while the call is still in progress.
secondsinteger | nullreqTalk time in whole seconds. null while the call is in progress or if it never connected.
outcomestringreqHow the call resolved, as determined by WAVV. Always present: a call that has not resolved yet reports UNKNOWN rather than null. Treat this list as open — new members may be added. One of: BUSY, DISCONNECTED, NO_ANSWER, HUNG_UP, USER_HUNG_UP, UNKNOWN, VOICEMAIL, CALLBACK, NO_VOICEMAIL, NO_CALLBACK, TRANSFERRED, VOICEMAIL_RETRY, REJECTED.
dispositionstring | nullreqThe free-text disposition the agent selected, drawn from your team's own configured list. null if none was set. Values are team-defined, not a WAVV enum.
humanboolean | nullreqWhether a human answered, according to WAVV's answering-machine detection. false means a machine was detected; null means no determination was made, which is a distinct result from false.
notestring | nullreqFree-text note the agent attached to the call. null if none.
summarystring | nullreqAI-generated call summary. Produced asynchronously after the call ends, so it is typically null on call.ended and populated shortly after.
recordedbooleanreqWhether audio was recorded. When true, fetch the audio from GET /calls/{id}/recording — the URL is never embedded in this object.
CallWithRecording — extends Call

A Call plus the signed recording URL. Used only as the data of a call.recorded event.

FieldTypeDescription
recordingUrlstring (uri)reqSigned, time-limited URL to the call audio. Generated at send time and valid for 72 hours. Download promptly; do not store the URL.
CallWithTranscript — extends Call

A Call plus its transcript. Returned only by list calls with includeTranscripts=true; never by GET /calls/{id} or in a webhook payload, which share the plain Call shape.

FieldTypeDescription
transcriptstring | nullreqThe full call transcript, as GET /calls/{id}/transcript returns it. null when the call was not transcribed, or the transcript is not ready yet. Can run to tens of kilobytes, which is why pages that carry it hold at most 25 calls.
CallListEnvelope

One page of calls.

FieldTypeDescription
dataCall[]reqThe page of calls, newest first. With includeTranscripts=true, each is a CallWithTranscript.
nextCursorstring | nullreqPass back as cursor for the next page. null on the last page.
RecordingUrl

A freshly signed link to a call's audio.

FieldTypeDescription
urlstring (uri)reqSigned URL to the audio file.
expiresAtstring (date-time)reqWhen the signature stops working — 72 hours from the request.
Transcript

Post-call text content. Both fields are populated asynchronously. Each is present only when part asks for it — both by default — so neither is marked required.

FieldTypeDescription
transcriptstring | nulloptFull call transcript. null if not transcribed, or not ready yet. Absent when part=summary.
summarystring | nulloptAI-generated summary. Same value as summary on the call object; null until it has been generated. Absent when part=transcript.
CallEvent

The envelope every webhook delivery uses.

FieldTypeDescription
eventstringreqWhich event fired. Branch your handler on this. One of: call.started, call.incoming, call.answered, call.ended, call.recorded, call.missed.
sentAtstring (date-time)reqWhen this payload was rendered. It is set once when the event is dispatched, so retries of the same delivery carry the original value. Use the t parameter in X-WAVV-Signature for freshness and replay checks.
dataCallreqThe canonical call shape. Identical in REST responses and webhook payloads. transcript is not part of it; fetch it from GET /calls/{id}/transcript, or list calls with includeTranscripts=true, which returns CallWithTranscript. Webhooks never carry it.
CallRecordedEvent — the call.recorded envelope

Identical to CallEvent, except data also carries recordingUrl.

FieldTypeDescription
eventstringreqAlways call.recorded.
sentAtstring (date-time)reqWhen this payload was rendered.
dataCallWithRecordingreqA Call plus the signed recording URL. Used only as the data of a call.recorded event.
InboundFlowList
FieldTypeDescription
flowsInboundFlow[]reqEvery live flow on the team, the default first.
defaultFlowIdstring (uuid) | nullreqThe flow numbers without a group flow run. null only while the team has no flows at all; creating the first flow sets it.
InboundFlow

One inbound flow with its current steps. steps is the stored definition, validated on save.

FieldTypeDescription
idstring (uuid)req
namestringreqThe name managers see in Dialer Settings › Inbound Flows.
isDefaultbooleanreqWhether this is the team default — the flow for numbers without a group flow. Exactly one flow is.
needsAttentionbooleanreqTrue when a step points at something that no longer exists, or forwards to a number that is no longer verified (see brokenLinks), or when the flow has a webhook step and the team's routing webhook isn't working (see routing). The flow still runs: a broken step is skipped, so the call falls through to the next step.
routingstring | nullreqFor a flow with a webhook step, how the team's routing webhook stands: ok; notSetUp (no endpoint, or turned off); paused (5 failures in 5 minutes, so WAVV stopped asking for 5 minutes). null for a flow without a webhook step. One of: ok, notSetUp, paused, null.
brokenLinksInboundFlowBrokenLink[]reqThe references that no longer resolve; empty when nothing is broken.
summarystringreqOne sentence, generated from the steps, saying what the flow does. Wording may change; branch on steps.
versionintegerreqThe version new calls run. Saving new steps increments it.
stepsInboundFlowStep[]reqThe ordered steps. See InboundFlowStep for each shape and the ordering rules.
usedByInboundFlowUsagereqWhich of the team's numbers run this flow.
createdAtstring (date-time)req
updatedAtstring (date-time)reqLast rename, new version, or other change to the flow row.
InboundFlowUsage

Which of the team's numbers run this flow.

FieldTypeDescription
numberGroupsobject[]reqThe number groups that picked this flow, with how many live numbers each holds.
numberCountintegerreqUngrouped numbers that point at this flow directly. Only migration sets that link; a number moved into a group uses the group's flow instead.
ungroupedNumberCountinteger | nullreqFor the team default only: the ungrouped numbers with no flow of their own, which it also covers (and any new number until it is grouped). null for every other flow.
FieldTypeDescription
stepIdstringreq
stepTypestringreq One of: callback, ringGroup, ringRep, webhook, hold, voicemail, forward, end.
kindstringreqWhat kind of thing the step pointed at. forwardNumber: a ringRep step's forwardTo is no longer verified, and id is that number. One of: memberGroup, rep, greeting, forwardNumber.
idstringreqThe id that no longer resolves.
InboundFlowStep

One step of a flow, told apart by type. The rules a saved list of steps must satisfy: - The first step is callback and no other step is. Turn it off with enabled: false rather than removing it. - voicemail, forward and end are optional and end the flow; when present, one of them is the last step. A call that runs past the last step is hung up. - At most one webhook step ("Ask your system"), and it is the second step, right after callback, so every step it can jump to comes after it. - Every id is unique within the flow (up to 64 characters). Keep ids stable across versions so the routing log can compare them. - Every step but callback can carry a key: a short name (lowercase letters, numbers and dashes, up to 32 characters, unique within the flow) that a routing webhook's goto reply uses to jump to the step. Steps run top to bottom; a goto is the only jump, and only forward. - Consecutive ringGroup steps make tiers: when a call moves straight from one ringGroup step to another whose order is all, the reps still ringing from the first keep ringing alongside the new group until someone answers. - A hold step answers the caller, and ring steps only ring a caller who hasn't been answered: ringGroup and ringRep steps after a hold are skipped, and the call goes on to a later hold step if there is one, else to the step that ends the flow. - ringSeconds is 5–60. Between one and twenty steps in all. - Ids inside a step must belong to the team: memberGroupIds are member group ids, userId (including box.userId and alert.userId) and the keys of weights are WAVV user ids (as wavvUserId on a board member), greetingId is a voicemail greeting the team or one of its members recorded. A ringRep step with forwardTo is checked by its number and who verified it instead.

InboundRoutingRequest

What a webhook step POSTs to the team's routing endpoint. Phone numbers are E.164.

FieldTypeDescription
eventstringreq
testbooleanreqTrue for a Send test from the settings page. Nothing is routed and nobody's phone rings.
callIdstringreqThe inbound call's id. Stable for the whole call, so use it to log and dedupe. It isn't guaranteed to match the call's id in /calls and call events.
flowobjectreq
stepobjectreqThe step that is asking.
fromstringreqThe caller.
tostringreqThe WAVV number they dialed.
forwardedFromstring | nullreqThe outside line that forwarded the call to to, when the carrier says so (the SIP Diversion header). null means not known, not "not forwarded".
contactobject | nullreqThe caller's contact in WAVV, when the number matches one. crmId is the id in your CRM.
callbackobject | nullreqThe rep who last called this caller, when the flow's callback step matched one.
availableRepsobject[]reqThe team's reps who could take the call right now: Available, connected, and not on a call. Use it to pick a free rep without a separate status lookup; match them to your own users by email.
stepKeysstring[]reqThe keys a goto reply can name — the keyed steps after the asking step. goto also accepts a step's id.
InboundRoutingReply

Your reply to a routing request, told apart by action (case-sensitive). Anything else sends the call to the next step and counts as a failure toward the pause. Ids and step are at most 64 characters.

InboundFlowCreate
FieldTypeDescription
namestringreq
stepsInboundFlowStep[]optThe steps, or leave out for the starter steps (callback on, then voicemail in the called-back rep's box, else the team's).
InboundFlowPatch

At least one of the three is required.

FieldTypeDescription
namestringopt
stepsInboundFlowStep[]optReplaces the whole list and becomes the next version.
baseVersionintegeroptThe version the new steps were built from. If the flow has moved past it, the save is refused with 409. Ignored without steps.
isDefaultbooleanoptMake this flow the team default.
Message

A text message, as delivered in every message.* webhook. Like the Call, its ids are yours: userId is the id you passed to POST /tokens, and contactId is your contact id.

FieldTypeDescription
idstring (uuid)reqWAVV's id for the message. Stable across the events for one message, so deduplicate on (event, id).
teamIdstring (uuid) | nullreqThe team the conversation belongs to.
userIdstring | nullreqYour id for the user — the sender of an outbound message, or the owner of the conversation an inbound one arrived in. null for a message received on a number the whole team shares, since no single user owns it.
conversationIdstring (uuid) | nullreqThe conversation thread the message belongs to. Every message in one thread shares it.
directionstringreqoutbound when your user sent it, inbound when the contact did. One of: outbound, inbound.
userNumberstring | nullreqThe WAVV number on your user's side of the conversation, whichever direction the message went.
contactNumberstring | nullreqThe contact's number, whichever direction the message went.
contactIdstring | nullreqYour id for the contact, when the conversation is linked to one of your contacts. null for a number WAVV has not matched to a contact of yours.
bodystringreqThe message text. Empty string for a message that carries only attachments.
attachmentsstring (uri)[]reqURLs of any images or files sent with the message. Empty when there are none.
segmentsintegerreqHow many SMS segments the carrier billed the body as.
statusstringreqMatches the event — sent on message.sent, and so on. One of: sent, received, failed.
failedReasonstring | nullreqWhy the carrier rejected the message, in words meant for a person. null unless status is failed.
createdAtstring (date-time)reqWhen WAVV created the message.
sentAtstring (date-time) | nullreqFor an outbound message, when the carrier accepted it; for an inbound one, when WAVV received it. null for an outbound message that failed before the carrier took it.
failedAtstring (date-time) | nullreqWhen the message failed. null unless status is failed.
MessageEvent

The envelope every message.* delivery uses — the same as CallEvent, with a Message in data.

FieldTypeDescription
eventstringreqWhich event fired. Branch your handler on this. One of: message.sent, message.received, message.failed.
sentAtstring (date-time)reqWhen this payload was rendered. Retries of the same delivery carry the original value.
dataMessagereqA text message, as delivered in every message.* webhook. Like the Call, its ids are yours: userId is the id you passed to POST /tokens, and contactId is your contact id.
Error

Every non-2xx REST response uses this shape.

FieldTypeDescription
errorstringreqHuman-readable message intended for logs and diagnostics. Branch on code rather than this field, as the wording may change.
codestringreqMachine-readable code — see Error codes.

Reference

Error codes

Every error response carries a machine-readable code. The known codes:

CodeMeaning
INVALID_API_KEYMissing, malformed, or revoked API key, or a Sign in with WAVV access token that is invalid or expired. Always 401.
FORBIDDENThe signed-in user may not use the API — their role is not owner, admin, or manager, or they are not on an active team. Also returned by the inbound flow endpoints when the team is not on inbound flows yet. 403.
NOT_FOUNDThe call does not exist, or belongs to another team. Also returned when a call exists but has no recording.
INVALID_REQUESTThe request was malformed, or a parameter failed validation. For inbound flows this includes a step that points at a member group, rep or greeting that is not on the team. 400.
CONFLICTThe change is refused in the team's current state: deleting an inbound flow that is the team default or that a number group still uses (change the default or the group's flow first), or saving steps to a flow someone else saved since it was read (read it again and resave). 409.
RATE_LIMITEDToo many requests. The response carries a Retry-After header giving the seconds to wait — see Rate limits. 429.
QUERY_TIMEOUTThe request took too long to answer and was stopped: 30 seconds for a call list, 60 for a call board report. Retrying the same request will likely time out again; narrow the date range or filters. 503.
SERVER_ERRORSomething failed on our side. Safe to retry. Usually 500; 503 when WAVV briefly can't check a credential.
Error response shape
{
  "error": "Call not found",
  "code": "NOT_FOUND"
}