Create Outbound Call
Place an outbound phone call using a Yappr agent (default), or — with type: "web" — mint a short-lived browser session token for an in-browser voice call via the @goyappr/client SDK. A phone call requires $3+ balance and an active Yappr phone number; if server capacity is fully utilized it is queued automatically and returns HTTP 202. A web session does not place a call and is not queued — it returns a token the visitor’s browser uses to connect.
Authorizations
Your Yappr API key (e.g. ypr_live_...). Generate one in the dashboard under Settings → API Keys.
Body
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.
phone, web 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 (+972followed 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.
"+972501234567"
Your active Yappr phone number in strict E.164 format. Same validation rules as to. Malformed numbers are rejected with 400 INVALID_FROM_NUMBER.
"+972551234567"
Key-value pairs injected as template variables into the agent's system prompt (e.g. {{LeadName}}).
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.
Web sessions only (type: web). Optional list of browser origins permitted to use the minted session (e.g. https://app.example.com).
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}.