Your first automated call

Six steps cover the minimum: authenticate, create a scenario, publish it, find a number, dial, read the result. You need a tenant that already exists, a trunk that is up, and one account with a user you can sign in as.

This walkthrough creates no agent, so the call runs as a test call against the scenario itself. Each step ends with an exit criterion: something you can call or hear that says the step is done.

Tip

If your tenant has not been issued yet, start with phase 1. Our team runs that phase with you; there is no self-service path into it.

1. Authenticate

   Sign in as a user of the account you will work in. Every request after this one carries the session token that comes back.

   POST/v1/auth/regular

   Exit criterion. The token authenticates a second request; a 401 means it did not.

2. Create a scenario

   The scenario is the call flow: what Voicebot says, what it listens for, where it branches.

   POST/v1/scenario

   Exit criterion. The response carries the scenario id. Every step below names it.

3. Publish a version

   A call runs a published version of the scenario, never the draft as it stands at dial time. Publishing takes the current draft and freezes it into an immutable version.

   There is no publish endpoint: the same write that saves a draft publishes the next version, and the request body decides which of the two it does.

   PATCH/v1/scenario/{id}

   The versions themselves are a separate resource, readable but never written directly.

   GET/v1/scenario-version

   Exit criterion. ListScenarioVersions returns a published version for your scenario. A scenario created as a draft has none until you publish one.

4. Find a number to dial from

   With no agent bound to the scenario, the call dials out from a free account number: one that is active and that no agent holds, either directly or through a pool. An agent records the numbers it holds. The number itself carries no such marker, so the number list alone cannot tell you which ones are free.

   GET/v1/number
   GET/v1/agent

   Exit criterion. ListNumbers returns at least one number with status: "active" that appears in no agent’s gateway.

5. Dispatch the call

   One request produces one call. Naming the scenario rather than an agent makes it a test call, so dial a handset you can answer.

   POST/v1/communication/-/dispatch

   Exit criterion. The dispatch returns 201 with a communication id, and the handset rings.

6. Read the outcome

   The call produces exactly one outcome. Read the communication until its status settles; the trace of the run is readable by the same id.

   GET/v1/communication/{id}
   GET/v1/communication/{id}/history

   Exit criterion. GetCommunication reports a status that no longer changes, and GetCommunicationHistory returns the run’s saved history.

What this covered

You have touched three of the four moving parts of an integration: authentication, configuration and consumption. The fourth is provisioning, and someone performed it for you in phase 1.

A test call dials one recipient once. Binding the same scenario to a gateway turns it into an agent, which answers a line and dials through it: POST/v1/agent.

When it does not work

Symptom	Cause
Dispatch answers 422	the scenario has no published version, or no account number is free
Dispatch accepted, nothing rings	the trunk is not up — see the SIP trunk
403 on a tenant endpoint	an account-level credential against the Tenant API
The communication sits in a live status	no terminal event reached it; the reconciler settles the row once its timeout passes — see drifted