Skip to main content
POST
Create outbound call, or mint a web-call session

Authorizations

Authorization
string
header
required

Your Yappr API key (e.g. ypr_live_...). Generate one in the dashboard under Settings → API Keys.

Body

application/json
agent_id
string<uuid>
required
type
enum<string>
default:phone

Call channel. Omit or "phone" places a normal outbound phone call (requires to and from). "web" mints a short-lived, single-use browser session token instead of dialing — no call is placed until the visitor's browser connects via the @goyappr/client SDK. For "web", only agent_id is used (to/from are ignored) and the 201 response is a session object.

Available options:
phone,
web
to
string

Destination phone number in strict E.164 format.

Validation rules (enforced at API and DB layers):

  • Must match ^\+[1-9][0-9]{7,14}$ — leading +, 8–15 digits, no spaces or dashes.
  • Israeli numbers (+972…) must be exactly 12 or 13 characters total (+972 followed by an 8-digit landline or 9-digit mobile).
  • Must differ from from.

Malformed numbers are rejected with 400 INVALID_TO_NUMBER — no row is written to the database, no carrier dial is attempted, and no capacity is consumed.

Example:

"+972501234567"

from
string

Your active Yappr phone number in strict E.164 format. Same validation rules as to. Malformed numbers are rejected with 400 INVALID_FROM_NUMBER.

Example:

"+972551234567"

variables
object

Key-value pairs injected as template variables into the agent's system prompt (e.g. {{LeadName}}).

Example:
metadata
object

Arbitrary key-value data attached to the call log record. Forwarded in real-time to every tool webhook as call_metadata so tool receivers (Make.com scenarios, n8n workflows, custom edge functions) can route updates back to the right CRM record without a secondary GET /calls/{id} fetch. Ideal for carrying IDs like appointment_id, contact_id, calendar_id. Not injected into the agent's system prompt.

Flow agents — contract callout. Flow agents can reference {{metadata.<key>}} tokens inside args_template values. Missing keys render to an empty string at runtime with no save-time or dispatch-time warning, so always check the agent's flow_config.metadata.custom_metadata_keys before placing the call and ensure every key in that array is supplied here.

Reserved keys. The five platform-supplied tokens (id, direction, agent_number, user_number, agent_name) are emitted by the platform at call start and cannot be overridden — using any of them as a key here is a 400 INVALID_METADATA_RESERVED_KEY. Pick a different name for your custom field.

Example:
allowed_origins
string[]

Web sessions only (type: web). Optional list of browser origins permitted to use the minted session (e.g. https://app.example.com).

Example:

Response

Call blocked because the destination is on the company's Do-Not-Call list. A call_logs row is recorded with status: "dnc_blocked" (so analytics + webhooks pick it up), but no carrier leg is established and no minutes are charged. To allow this number again, remove its DNC entry via DELETE /do-not-call/{id}.

call_id
string<uuid> | null
status
string
Example:

"dnc_blocked"

agent_id
string<uuid>
to
string
from
string
message
string
dnc_reason
string | null
started_at
string<date-time>
ended_at
string<date-time>