Connect your communications to your AI.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
One-time acceptance of the Widely Errands terms, needed before any AI call or errand can dial. Without confirm it returns a short terms summary, the link to the full terms, and whether this user already accepted. Show that to the user; only after the user clearly agrees, call again with confirm=true to record the acceptance. Safe to repeat.
true only after the user has agreed to the terms shown.
This tool isn't marked read-only, so it may change something on the server or in an account you connected.
Tool list last changed Oct 25, 2026.
One-time acceptance of the Widely Errands terms, needed before any AI call or errand can dial. Without confirm it returns a short terms summary, the link to the full terms, and whether this user already accepted. Show that to the user; only after the user clearly agrees, call again with confirm=true to record the acceptance. Safe to repeat.
| Argument | Type | Description |
|---|---|---|
| confirm | boolean | true only after the user has agreed to the terms shown. |
{
"type": "object",
"properties": {
"confirm": {
"type": "boolean",
"description": "true only after the user has agreed to the terms shown."
}
},
"additionalProperties": false
}Information only. Returns the ways to stop charges without closing the account (cancel membership, stop a number renewing, remove a saved card), and that unused credit is refunded on closure. Account closure and deletion are handled by Widely Support. This tool does not close or delete anything. No sign-in.
No arguments.
{
"type": "object",
"properties": {},
"additionalProperties": false
}Writes a message into this user's Widely Support chat and notifies the Support team. A person on the team replies in that chat (not instantly); call read_support to get the reply. Any connected account can send it. text is what is needed and what was already tried.
| Argument | Type | Description |
|---|---|---|
| text* | string |
{
"type": "object",
"required": [
"text"
],
"properties": {
"text": {
"type": "string"
}
},
"additionalProperties": false
}Stops an Errands task. graceful records a wrap-up and hangs up. immediate hangs up. A task that has not dialled is cancelled without a call.
| Argument | Type | Description |
|---|---|---|
| mode | string | |
| task_id* | string |
{
"type": "object",
"required": [
"task_id"
],
"properties": {
"mode": {
"enum": [
"graceful",
"immediate"
],
"type": "string"
},
"task_id": {
"type": "string"
}
},
"additionalProperties": false
}Places or schedules an Errands call from a brief. The price comes from the rate sheet. A future schedule_at waits until then. There is no global calling-hours window. Fill every field you can; call describe_errand_template for the fields and examples. Emergency and premium-rate numbers are refused. A marketing brief is refused. The seat needs the current Errands terms. Business plan. A bad brief lists every missing and invalid field at once. The assistant introduces itself with the name set in the user's Widely AI assistant settings (Assistant's name).
| Argument | Type | Description |
|---|---|---|
| goal* | string | The outcome you want, in one or two sentences. |
| limits | object | |
| callback | object | |
| language | string | BCP-47 such as en-GB or he-IL, or auto-from-seat. |
| forbidden | array | Things the assistant must not say or agree to. |
| ivr_hints | array | Phone menu hints, e.g. 'choose imports'. |
| voicemail | string | On voicemail: leave_message (default), hang_up_and_retry (uses limits.retry), or hang_up. |
| escalation | object | |
Stops one receptionist from using its informational opening-hours schedule. It does not change DID open/closed routing.
| Argument | Type | Description |
|---|---|---|
| ivr_config_id* | string |
{
"type": "object",
"required": [
"ivr_config_id"
],
"properties": {
"ivr_config_id": {
"type": "string"
}
},
"additionalProperties": false
}Deletes one categorized service, price, policy, FAQ, inventory, returns, donation, escalation, or custom fact.
| Argument | Type | Description |
|---|---|---|
| id* | string | |
| ivr_config_id* | string |
{
"type": "object",
"required": [
"ivr_config_id",
"id"
],
"properties": {
"id": {
"type": "string"
},
"ivr_config_id": {
"type": "string"
}
},
"additionalProperties": false
}Deletes one structured location from a receptionist.
| Argument | Type | Description |
|---|---|---|
| id* | string | |
| ivr_config_id* | string |
{
"type": "object",
"required": [
"ivr_config_id",
"id"
],
"properties": {
"id": {
"type": "string"
},
"ivr_config_id": {
"type": "string"
}
},
"additionalProperties": false
}Returns the Errands brief fields (required and optional, with shapes and allowed values), the rules the assistant always follows, and worked examples. Read-only. The assistant introduces itself with the name in Widely AI assistant settings (Settings → Voicemail → Configure Personal Assistant → Assistant's name). assistant_name overrides it for one errand; save_as_default true also saves it as the default. With neither, the call is refused: set it with set_assistant_name.
No arguments.
{
"type": "object",
"properties": {},
"additionalProperties": false
}Find a home mobile service Widely can provide for a country, including eSIM or physical SIM, native voice, SMS, a mobile number, and a regular or kosher line when the offer includes it. No sign-in. An empty list means nothing is listed yet. Travel data for a trip is a separate Widely product.
| Argument | Type | Description |
|---|---|---|
| country | string | Country name or two-letter code. |
| capability | string | One capability the offer declares, such as native_voice, sms, mobile_number, or number_porting. |
| form_factor | string | esim or physical_sim. |
| number_line | string | regular or kosher. Returned only when the offer lists that line. |
| capabilities | array | Every capability the offer declares. A missing one is left out. |
| service_type | string |
{
"type": "object",
"properties": {
"country": {
"type": "string",
"description": "Country name or two-letter code."
},
"capability": {
"type": "string",
"description": "One capability the offer declares, such as native_voice, sms, mobile_number, or number_porting."
},
"form_factor": {
"type": "string",
"description": "esim or physical_sim."
},
"number_line": {
"type": "string",
"description": "regular or kosher. Returned only when the offer lists that line."
},
"capabilities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Every capability the offer declares. A missing one is left out."
},
"service_type": {
"type": "string"
}
},
"additionalProperties": false
}Returns the eSIM install path and the APN. The APN is null when this profile has no APN. No sign-in.
No arguments.
{
"type": "object",
"properties": {},
"additionalProperties": false
}Returns charges already on this account, with amounts and labels. An empty list means there is no matching charge.
| Argument | Type | Description |
|---|---|---|
| question | string |
{
"type": "object",
"properties": {
"question": {
"type": "string"
}
},
"additionalProperties": false
}Returns the plan, the live wallet balance (the same headline as Home and Wallet), how many people are on the account, how many eSIMs are live, and which setups this seat can run.
No arguments.
{
"type": "object",
"properties": {},
"additionalProperties": false
}Returns whether auto top-up is on, and the threshold and amount.
No arguments.
{
"type": "object",
"properties": {},
"additionalProperties": false
}Returns full detail for one phone call, identified by call_id, including which identity and provider carried it.
| Argument | Type | Description |
|---|---|---|
| call_id* | string |
{
"type": "object",
"required": [
"call_id"
],
"properties": {
"call_id": {
"type": "string"
}
},
"additionalProperties": false
}Returns one Errands task: status, quote, collected facts, and recent events.
| Argument | Type | Description |
|---|---|---|
| task_id* | string |
{
"type": "object",
"required": [
"task_id"
],
"properties": {
"task_id": {
"type": "string"
}
},
"additionalProperties": false
}Returns this customer's pay-as-you-go data ladder, starting from data already used this period. This is the account rate, separate from the public shelf. Omitting gb returns the volume points.
| Argument | Type | Description |
|---|---|---|
| gb | number | Gigabytes they expect. Omit when they have not said. |
| country* | string | ISO-2 or country name. |
{
"type": "object",
"required": [
"country"
],
"properties": {
"gb": {
"type": "number",
"description": "Gigabytes they expect. Omit when they have not said."
},
"country": {
"type": "string",
"description": "ISO-2 or country name."
}
},
"additionalProperties": false
}Returns an indicative monthly phone-number price for a country, using this account's rate checker.
| Argument | Type | Description |
|---|---|---|
| country* | string | |
| number_type | string |
{
"type": "object",
"required": [
"country"
],
"properties": {
"country": {
"type": "string"
},
"number_type": {
"type": "string"
}
},
"additionalProperties": false
}Returns the result of an eSIM connection check for request_id, including fail and warn items. Phone settings are not changed.
| Argument | Type | Description |
|---|---|---|
| request_id* | string |
{
"type": "object",
"required": [
"request_id"
],
"properties": {
"request_id": {
"type": "string"
}
},
"additionalProperties": false
}Returns how this seat's numbers are forwarded. Pro plan.
No arguments.
{
"type": "object",
"properties": {},
"additionalProperties": false
}Returns notification toggles and the low-balance threshold.
No arguments.
{
"type": "object",
"properties": {},
"additionalProperties": false
}Returns the current status of a port request. A port is not instant.
| Argument | Type | Description |
|---|---|---|
| port_id* | string |
{
"type": "object",
"required": [
"port_id"
],
"properties": {
"port_id": {
"type": "string"
}
},
"additionalProperties": false
}Returns one product-note thread by conversation_id, oldest first. No account is required. Does not list other threads.
| Argument | Type | Description |
|---|---|---|
| conversation_id* | string |
{
"type": "object",
"required": [
"conversation_id"
],
"properties": {
"conversation_id": {
"type": "string"
}
},
"additionalProperties": false
}Returns one receptionist's profile, contacts, locations, opening hours, and categorized business facts before you update them.
| Argument | Type | Description |
|---|---|---|
| ivr_config_id* | string |
{
"type": "object",
"required": [
"ivr_config_id"
],
"properties": {
"ivr_config_id": {
"type": "string"
}
},
"additionalProperties": false
}Returns a short-lived streaming link for a recorded phone call. Business plan, and the grant includes recordings.read.
| Argument | Type | Description |
|---|---|---|
| call_id* | string |
{
"type": "object",
"required": [
"call_id"
],
"properties": {
"call_id": {
"type": "string"
}
},
"additionalProperties": false
}Returns messages in one thread, oldest first. before is an ISO 8601 cursor for older pages.
| Argument | Type | Description |
|---|---|---|
| limit | integer | Max rows to return. |
| before | string | |
| conversation_id* | string |
{
"type": "object",
"required": [
"conversation_id"
],
"properties": {
"limit": {
"type": "integer",
"maximum": 50,
"minimum": 1,
"description": "Max rows to return."
},
"before": {
"type": "string"
},
"conversation_id": {
"type": "string"
}
},
"additionalProperties": false
}Returns stored transcript text already saved for a phone call. Does not start a new transcription. While speaking is still in progress, the status is in_progress. Returns no_transcript only after the conversation has ended with no stored text.
| Argument | Type | Description |
|---|---|---|
| call_id* | string |
{
"type": "object",
"required": [
"call_id"
],
"properties": {
"call_id": {
"type": "string"
}
},
"additionalProperties": false
}Returns the eSIM data balance and minutes already used on this seat. company=true covers the whole account on Business.
| Argument | Type | Description |
|---|---|---|
| days | integer | Look back this many days (default 30). |
| company | boolean |
{
"type": "object",
"properties": {
"days": {
"type": "integer",
"maximum": 3650,
"minimum": 1,
"description": "Look back this many days (default 30)."
},
"company": {
"type": "boolean"
}
},
"additionalProperties": false
}Returns one voicemail by call_id, including its transcript. include_audio also returns a short-lived audio link on Pro and above.
| Argument | Type | Description |
|---|---|---|
| call_id* | string | |
| include_audio | boolean |
{
"type": "object",
"required": [
"call_id"
],
"properties": {
"call_id": {
"type": "string"
},
"include_audio": {
"type": "boolean"
}
},
"additionalProperties": false
}Emails an invitation to join this Widely account. New users start Free; there is no account user limit.
| Argument | Type | Description |
|---|---|---|
| email* | string |
{
"type": "object",
"required": [
"email"
],
"properties": {
"email": {
"type": "string"
}
},
"additionalProperties": false
}Lists this seat's Errands tasks. Filter by status or date.
| Argument | Type | Description |
|---|---|---|
| limit | integer | |
| since | string | |
| until | string | |
| status | string |
{
"type": "object",
"properties": {
"limit": {
"type": "integer",
"maximum": 50,
"minimum": 1
},
"since": {
"type": "string",
"format": "date-time"
},
"until": {
"type": "string",
"format": "date-time"
},
"status": {
"type": "string"
}
},
"additionalProperties": false
}Returns this account's phone numbers, including numbers that stay inactive until identity registration is finished.
No arguments.
{
"type": "object",
"properties": {},
"additionalProperties": false
}Returns the phone numbers, caller IDs, verified SIM numbers, PBX extensions, and eSIMs on this Widely seat, with the provider that supplies each and what it can do.
| Argument | Type | Description |
|---|---|---|
| include_shared | boolean | Include account shared numbers. This user and the account owner need Business. |
{
"type": "object",
"properties": {
"include_shared": {
"type": "boolean",
"description": "Include account shared numbers. This user and the account owner need Business."
}
},
"additionalProperties": false
}Returns masked saved cards and bank methods: brand, last4, and default. A processor id is not included.
No arguments.
{
"type": "object",
"properties": {},
"additionalProperties": false
}Returns numbers and who answers them, AI receptionists with greeting, knowledge, voice, and languages, press-1 menus, queues, and opening hours with the weekly windows. The owner needs Business for shared phone-system features; queue agents, shared-number users, and direct person targets need Business too. A queue rings only members who are signed in and available.
No arguments.
{
"type": "object",
"properties": {},
"additionalProperties": false
}List Free, Pro, and Business monthly prices. Each monthly figure is per user. Quote that amount. Do not round it and do not call it an account price. No sign-in. This does not change the plan. Business covers the office phone system. channel_packs lists the 10-channel pack prices: number packs per country, and SIP trunk packs per account.
| Argument | Type | Description |
|---|---|---|
| currency | string | GBP, EUR, USD, or ILS. Defaults to EUR. |
{
"type": "object",
"properties": {
"currency": {
"type": "string",
"description": "GBP, EUR, USD, or ILS. Defaults to EUR."
}
},
"additionalProperties": false
}Returns people on this account and pending email invites.
No arguments.
{
"type": "object",
"properties": {},
"additionalProperties": false
}Returns recent voicemails on this seat with caller, time, duration, and transcript text when one is stored.
| Argument | Type | Description |
|---|---|---|
| days | integer | Look back this many days (default 30). |
| limit | integer | Max rows to return. |
{
"type": "object",
"properties": {
"days": {
"type": "integer",
"maximum": 3650,
"minimum": 1,
"description": "Look back this many days (default 30)."
},
"limit": {
"type": "integer",
"maximum": 50,
"minimum": 1,
"description": "Max rows to return."
}
},
"additionalProperties": false
}Returns the wallet ledger of top-ups, product debits, and holds. Each row includes the customer label.
| Argument | Type | Description |
|---|---|---|
| limit | integer | |
| offset | integer |
{
"type": "object",
"properties": {
"limit": {
"type": "integer",
"maximum": 200,
"minimum": 1
},
"offset": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": false
}Returns first-eSIM wallet top-ups that can be refunded to the card: the profile has not been installed and the top-up is inside the refund window.
No arguments.
{
"type": "object",
"properties": {},
"additionalProperties": false
}Returns the documents a number port needs. No sign-in. Does not submit a port.
No arguments.
{
"type": "object",
"properties": {},
"additionalProperties": false
}Returns the per-minute price for dialling a destination number or country. Signed in, it is this account's rate (account_rate true). Not signed in, it is the public list price (list_price true). This does not place the call.
| Argument | Type | Description |
|---|---|---|
| country | string | |
| currency | string | GBP, EUR, USD, or ILS. Omit for the rate-checker default. |
| destination | string | Phone number to price. |
| number_type | string |
{
"type": "object",
"properties": {
"country": {
"type": "string"
},
"currency": {
"type": "string",
"description": "GBP, EUR, USD, or ILS. Omit for the rate-checker default."
},
"destination": {
"type": "string",
"description": "Phone number to price."
},
"number_type": {
"type": "string"
}
},
"additionalProperties": false
}Prices an Errands brief from the call rate sheet, including the ai_task minute. Returns the caller ID and the cost at max_call_minutes. No rate refuses the call. Emergency and premium-rate numbers are refused. A marketing brief is refused. The seat needs the current Errands terms. A bad brief lists every missing and invalid field at once. This does not dial.
| Argument | Type | Description |
|---|---|---|
| goal* | string | The outcome you want, in one or two sentences. |
| limits | object | |
| callback | object | |
| language | string | BCP-47 such as en-GB or he-IL, or auto-from-seat. |
| forbidden | array | Things the assistant must not say or agree to. |
| ivr_hints | array | Phone menu hints, e.g. 'choose imports'. |
| voicemail | string | On voicemail: leave_message (default), hang_up_and_retry (uses limits.retry), or hang_up. |
| escalation | object | |
Price Widely travel data for a country. Use this when a trip needs data and not a home mobile service. Pay as you go per GB, with no data package. An optional gb value returns an estimate billed in 0.1 GiB steps. No sign-in.
| Argument | Type | Description |
|---|---|---|
| gb | number | Optional amount of data to estimate. |
| country* | string | |
| currency | string | GBP, EUR, USD, or ILS. Omit for the rate-checker default. |
{
"type": "object",
"required": [
"country"
],
"properties": {
"gb": {
"type": "number",
"description": "Optional amount of data to estimate."
},
"country": {
"type": "string"
},
"currency": {
"type": "string",
"description": "GBP, EUR, USD, or ILS. Omit for the rate-checker default."
}
},
"additionalProperties": false
}Price a Widely phone number for a country, including the monthly amount and whether local calls are included. Use this when a UK, US, Israeli, or other local number is needed. Each number includes 2 simultaneous calls. More come in packs of 10, shared by the account's numbers in the same country; channel_count prices the packs needed for a total such as 15. No sign-in. This does not purchase the number.
| Argument | Type | Description |
|---|---|---|
| country* | string | |
| currency | string | GBP, EUR, USD, or ILS. Omit for the rate-checker default. |
| number_type | string | |
| channel_count | integer | Total simultaneous calls wanted, including the 2 included. |
{
"type": "object",
"required": [
"country"
],
"properties": {
"country": {
"type": "string"
},
"currency": {
"type": "string",
"description": "GBP, EUR, USD, or ILS. Omit for the rate-checker default."
},
"number_type": {
"type": "string"
},
"channel_count": {
"type": "integer",
"minimum": 2,
"description": "Total simultaneous calls wanted, including the 2 included."
}
},
"additionalProperties": false
}Price moving an existing number onto Widely. Use this when the current number should be kept. The move is not instant. No sign-in. This does not start the move.
| Argument | Type | Description |
|---|---|---|
| number | string | |
| country | string | |
| currency | string | GBP, EUR, USD, or ILS. Omit for the rate-checker default. |
| number_type | string |
{
"type": "object",
"properties": {
"number": {
"type": "string"
},
"country": {
"type": "string"
},
"currency": {
"type": "string",
"description": "GBP, EUR, USD, or ILS. Omit for the rate-checker default."
},
"number_type": {
"type": "string"
}
},
"additionalProperties": false
}Price one listed home mobile service for a form factor and number line that offer allows. The amount comes from that offer. No sign-in. This is separate from Widely travel data.
| Argument | Type | Description |
|---|---|---|
| number | string | |
| offer_id* | string | |
| form_factor* | string | |
| number_line* | string | regular or kosher, when the offer allows it. |
{
"type": "object",
"required": [
"offer_id",
"form_factor",
"number_line"
],
"properties": {
"number": {
"type": "string"
},
"offer_id": {
"type": "string"
},
"form_factor": {
"type": "string"
},
"number_line": {
"type": "string",
"description": "regular or kosher, when the offer allows it."
}
},
"additionalProperties": false
}Returns messages in this user's Support chat, oldest first. Any connected account can read it. Other chats are not included.
| Argument | Type | Description |
|---|---|---|
| limit | integer | Max rows to return. |
{
"type": "object",
"properties": {
"limit": {
"type": "integer",
"maximum": 50,
"minimum": 1,
"description": "Max rows to return."
}
},
"additionalProperties": false
}Rings the user's phones. After one answers, dials the destination into that same conversation. The result shows as an outgoing phone call. The user speaks on it. Pro plan. If no phone answers, the destination is not dialled.
| Argument | Type | Description |
|---|---|---|
| destination | string | Phone number to connect after the user answers. |
| identity_id | string | Optional. You may set it. If you omit it, Widely picks the caller ID. If you set it, it must be an identity_id from list_identities, one of the user's own. Never invent another number. A grant limited to several numbers still needs identity_id. |
{
"type": "object",
"properties": {
"destination": {
"type": "string",
"description": "Phone number to connect after the user answers."
},
"identity_id": {
"type": "string",
"description": "Optional. You may set it. If you omit it, Widely picks the caller ID. If you set it, it must be an identity_id from list_identities, one of the user's own. Never invent another number. A grant limited to several numbers still needs identity_id."
}
},
"additionalProperties": false
}Dials the number and the assistant handles the errand on the phone. Business plan. Takes a structured brief only (call describe_errand_template for the fields); free text is refused. A bad brief lists every missing and invalid field at once. The assistant introduces itself with the name in the user's Widely AI assistant settings, or brief.assistant_name; with neither the call is refused (set it with set_assistant_name). It agrees only to allowed_commitments, leaves a voicemail by default, and always ends with a thank-you and goodbye. Returns immediately with the task and call ids.
| Argument | Type | Description |
|---|---|---|
| brief* | object | The structured errand brief. destination may be given here or at the top level. |
| destination | string | Number to call. brief.destination wins when both are set. |
| identity_id | string | Optional. You may set it. If you omit it, Widely picks the caller ID. If you set it, it must be an identity_id from list_identities, one of the user's own. Never invent another number. |
{
"type": "object",
"required": [
"brief"
],
"properties": {
"brief": {
"type": "object",
"required": [
"callee_name",
"goal",
"on_behalf_of",
"purpose_category",
"success_criteria"
],
"properties": {
"goal": {
"type": "string",
"maxLength": 500,
"minLength": 8,
"description": "The outcome you want, in one or two sentences."
},
"limits": {
"type": "object",
"properties": {
"retry": {
"type": "object",
"properties": {
"gap_minutes": {
"type": "integer",
"minimum": 0
},
"on_busy_or_no_answer": {
"type": "integer",
"default": 0,
"maximum": 3,
"minimum": 0
}
},
"additionalProperties": false
},
"max_cost": {
"type": "number",
"minimum": 0
},
"max_ivr_minutes": {
"type": "integer",
"default": 6,
"maximum": 15,
"minimum": 1
},
"max_call_minutes": {
"type": "integer",
"default": 30,
"maximum": 120,
"minimum": 1
},
"max_hold_minutes": {
"type": "integer",
"default": 20,
"maximum": 90,
"minimum": 0
}
},
"additionalProperties": false
},
"callback": {
"type": "object",
"properties": {
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"webhook_url": {
"type": "string",
"format": "uri",
"description": "https URL for task events."
}
},
"additionalProperties": false
},
"language": {
"type": "string",
"maxLength": 40,
"description": "BCP-47 such as en-GB or he-IL, or auto-from-seat."
},
"forbidden": {
"type": "array",
"items": {
"type": "string",
"maxLength": 200
},
"maxItems": 10,
"description": "Things the assistant must not say or agree to."
},
"ivr_hints": {
"type": "array",
"items": {
"type": "string",
"maxLength": 200
},
"maxItems": 20,
"description": "Phone menu hints, e.g. 'choose imports'."
},
"voicemail": {
"enum": [
"leave_message",
"hang_up_and_retry",
"hang_up"
],
"type": "string",
"default": "leave_message",
"description": "On voicemail: leave_message (default), hang_up_and_retry (uses limits.retry), or hang_up."
},
"escalation": {
"type": "object",
"properties": {
"mode": {
"enum": [
"never",
"on_request",
"on_human",
"on_blocker"
],
"type": "string",
"default": "on_blocker"
},
"notify": {
"enum": [
"app",
"whatsapp",
"both"
],
"type": "string",
"default": "app"
},
"blockers": {
"type": "array",
"items": {
"enum": [
"verification_failed",
"asks_for_account_holder",
"payment_requested",
"legal_or_dispute",
"callee_requests_human",
"unknown_fact_needed"
],
"type": "string"
}
},
"ring_user_after_seconds": {
"type": "integer",
"default": 60,
"maximum": 600,
"minimum": 0
}
},
"additionalProperties": false
},
"if_unknown": {
"enum": [
"say_will_check_back",
"escalate",
"end_politely"
],
"type": "string",
"default": "say_will_check_back",
"description": "What to do when asked something the brief does not cover."
},
"callee_name": {
"type": "string",
"maxLength": 120,
"description": "Who you are calling, e.g. 'FedEx UK Import Clearance' or 'Dr Cohen's clinic'."
},
"destination": {
"type": "string",
"maxLength": 32,
"description": "Number to call, E.164 (+44…, +972…, +1…) or local. Emergency and premium-rate numbers are refused."
},
"schedule_at": {
"type": "string",
"format": "date-time",
"description": "When to call, ISO date-time, at most 14 days ahead. Omit it to call now."
},
"time_window": {
"type": "object",
"required": [
"not_before",
"not_after"
],
"properties": {
"not_after": {
"type": "string",
"format": "date-time",
"description": "ISO date-time with offset."
},
"not_before": {
"type": "string",
"format": "date-time",
"description": "ISO date-time with offset."
}
},
"description": "Optional calling window, at least 10 minutes long and within 14 days. The call is placed inside it.",
"additionalProperties": false
},
"connect_user": {
"type": "boolean",
"default": false,
"description": "When true, the assistant asks the callee to hold at the end, rings the user's phones into the call, and leaves."
},
"on_behalf_of": {
"type": "object",
"required": [
"person"
],
"properties": {
"person": {
"type": "string",
"maxLength": 120,
"description": "Name of the person the call is for."
},
"company": {
"type": "string",
"maxLength": 120,
"description": "Company, if the call is for a business."
},
"relationship": {
"type": "string",
"maxLength": 120,
"description": "e.g. 'account holder', 'director', 'parent'."
}
},
"description": "Who the call is for. person is required.",
"additionalProperties": false
},
"opening_line": {
"type": "string",
"maxLength": 200,
"description": "Optional. What to say first, after the assistant introduces itself and plays the mandatory notice."
},
"facts_to_give": {
"type": "array",
"items": {
"type": "object",
"required": [
"key",
"value"
],
"properties": {
"key": {
"type": "string",
"maxLength": 80,
"description": "Short label, e.g. 'order_number'."
},
"value": {
"type": "string",
"maxLength": 300,
"description": "The fact."
},
"disclose": {
"enum": [
"freely",
"if_asked",
"only_to_verified_human",
"never"
],
"type": "string",
"default": "if_asked"
}
},
"additionalProperties": false
},
"maxItems": 30,
"description": "Facts the assistant may give. Card numbers, CVVs, PINs and passwords are refused."
},
"assistant_name": {
"type": "string",
"maxLength": 40,
"description": "Optional. The name the assistant uses on this call instead of the AI assistant settings name."
},
"save_as_default": {
"type": "boolean",
"default": false,
"description": "With assistant_name, also save it as the default name in Widely AI assistant settings."
},
"client_reference": {
"type": "string",
"maxLength": 100,
"description": "Your own reference."
},
"facts_to_collect": {
"type": "array",
"items": {
"type": "object",
"required": [
"key",
"description"
],
"properties": {
"key": {
"type": "string",
"pattern": "^[a-z0-9_]{1,40}$"
},
"type": {
"enum": [
"string",
"number",
"date",
"boolean",
"money",
"reference"
],
"type": "string",
"default": "string"
},
"required": {
"type": "boolean",
"default": true
},
"description": {
"type": "string",
"maxLength": 300,
"description": "The question to ask or the information needed."
},
"confirm_back": {
"type": "boolean",
"default": true
}
},
"additionalProperties": false
},
"maxItems": 20,
"description": "Questions to ask and the information to bring back."
},
"purpose_category": {
"enum": [
"service_enquiry",
"account_admin",
"booking",
"logistics",
"complaint",
"other_non_marketing"
],
"type": "string",
"description": "Kind of call. Marketing, sales, surveys, debt collection, political and fundraising calls are refused."
},
"success_criteria": {
"type": "array",
"items": {
"type": "string",
"maxLength": 200
},
"maxItems": 10,
"minItems": 1,
"description": "How to tell the call worked, e.g. 'they confirm the delivery date'."
},
"voicemail_message": {
"type": "string",
"maxLength": 300,
"description": "Optional. If absent, the assistant leaves a short message from the goal and on_behalf_of, with no sensitive facts."
},
"callee_is_business": {
"type": "boolean",
"description": "Optional. True when the callee is a business."
},
"caller_identity_id": {
"type": "string",
"maxLength": 64,
"description": "Optional. You may set it. If you omit it, Widely picks the caller ID. If you set it, it must be an identity_id from list_identities, one of the user's own. Never invent another number."
},
"allowed_commitments": {
"type": "array",
"items": {
"type": "string",
"maxLength": 200
},
"maxItems": 10,
"description": "The only things the assistant may agree to, e.g. 'accept any slot Tue–Thu after 14:00'. For anything else it says it will check and come back, and lists it in the report. Payments, contracts and cancellations are never allowed."
}
},
"description": "The structured errand brief. destination may be given here or at the top level.",
"additionalProperties": false
},
"destination": {
"type": "string",
"description": "Number to call. brief.destination wins when both are set."
},
"identity_id": {
"type": "string",
"description": "Optional. You may set it. If you omit it, Widely picks the caller ID. If you set it, it must be an identity_id from list_identities, one of the user's own. Never invent another number."
}
},
"additionalProperties": false
}Asks Widely to transcribe a recording that has no text yet. Pro plan.
| Argument | Type | Description |
|---|---|---|
| call_id* | string |
{
"type": "object",
"required": [
"call_id"
],
"properties": {
"call_id": {
"type": "string"
}
},
"additionalProperties": false
}Asks this user's Widely app to check the eSIM and returns a request_id. A result of no_install_yet means the profile may have been installed from a QR and the Widely app is not on that phone. An APN is not included.
| Argument | Type | Description |
|---|---|---|
| sim_id | string | |
| device_id | string |
{
"type": "object",
"properties": {
"sim_id": {
"type": "string"
},
"device_id": {
"type": "string"
}
},
"additionalProperties": false
}Finds phone calls on this Widely seat by date range, direction, contact name, or number. Returns one row per phone call, with direction, duration, outcome, the identity used, and whether a transcript or recording exists.
| Argument | Type | Description |
|---|---|---|
| days | integer | Look back this many days (default 30). |
| line | string | |
| limit | integer | Max rows to return. |
| query | string | Words from a stored transcript. Pro. |
| since | string | ISO 8601 start (inclusive). |
| until | string | ISO 8601 end (exclusive). |
| number | string | Phone number or trailing digits. |
| contact | string | Saved contact name to match. |
| direction | string | |
| missed_only | boolean |
Finds saved contacts on this seat by name. Returns names and phone numbers.
| Argument | Type | Description |
|---|---|---|
| limit | integer | |
| query* | string |
{
"type": "object",
"required": [
"query"
],
"properties": {
"limit": {
"type": "integer",
"maximum": 25,
"minimum": 1
},
"query": {
"type": "string"
}
},
"additionalProperties": false
}Returns public product facts and in-app menu names for a question. No sign-in. Does not return a price.
| Argument | Type | Description |
|---|---|---|
| query* | string |
{
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string"
}
},
"additionalProperties": false
}Searches this user's Widely, SMS, and WhatsApp threads by keyword and date. Returns message text with sender and thread. Support and assistant threads are excluded.
| Argument | Type | Description |
|---|---|---|
| days | integer | Look back this many days (default 30). |
| limit | integer | Max rows to return. |
| query | string | Keyword to match in message text. |
| conversation_id | string |
{
"type": "object",
"properties": {
"days": {
"type": "integer",
"maximum": 3650,
"minimum": 1,
"description": "Look back this many days (default 30)."
},
"limit": {
"type": "integer",
"maximum": 50,
"minimum": 1,
"description": "Max rows to return."
},
"query": {
"type": "string",
"description": "Keyword to match in message text."
},
"conversation_id": {
"type": "string"
}
},
"additionalProperties": false
}Find Widely phone numbers available for a country and an optional city, with the monthly price. Use this when a local number is needed. No sign-in. This does not purchase a number.
| Argument | Type | Description |
|---|---|---|
| city | string | |
| country* | string | Two-letter country code or country name. |
| currency | string | GBP, EUR, USD, or ILS. Omit for the rate-checker default. |
| number_type | string | local, mobile, or toll-free. |
{
"type": "object",
"required": [
"country"
],
"properties": {
"city": {
"type": "string"
},
"country": {
"type": "string",
"description": "Two-letter country code or country name."
},
"currency": {
"type": "string",
"description": "GBP, EUR, USD, or ILS. Omit for the rate-checker default."
},
"number_type": {
"type": "string",
"description": "local, mobile, or toll-free."
}
},
"additionalProperties": false
}Sends an SMS or a Widely message to a phone number or saved contact. Pro plan. Sending happens on this request.
| Argument | Type | Description |
|---|---|---|
| to | string | Phone number or saved contact name. |
| text | string | Message text. |
| identity_id | string | Optional identity id when the grant is limited to specific numbers. |
{
"type": "object",
"properties": {
"to": {
"type": "string",
"description": "Phone number or saved contact name."
},
"text": {
"type": "string",
"description": "Message text."
},
"identity_id": {
"type": "string",
"description": "Optional identity id when the grant is limited to specific numbers."
}
},
"additionalProperties": false
}Sets the name the assistant uses on AI calls (Widely AI assistant settings → Assistant's name). Calls are refused until a name is set or passed in the brief.
| Argument | Type | Description |
|---|---|---|
| name* | string |
{
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 40
}
},
"additionalProperties": false
}Sets what happens when this seat declines a call, does not answer it, or is busy: voicemail, busy, decline, end, or ai_receptionist. ai_receptionist rings the seat first, then hands the call to the AI receptionist or phone menu in menu_id (Business).
| Argument | Type | Description |
|---|---|---|
| when* | string | |
| action* | string | |
| menu_id | string | AI receptionist or phone menu id, for ai_receptionist. |
{
"type": "object",
"required": [
"when",
"action"
],
"properties": {
"when": {
"enum": [
"decline",
"no_answer",
"busy"
],
"type": "string"
},
"action": {
"enum": [
"voicemail",
"busy",
"decline",
"end",
"ai_receptionist"
],
"type": "string"
},
"menu_id": {
"type": "string",
"description": "AI receptionist or phone menu id, for ai_receptionist."
}
},
"additionalProperties": false
}Points a number at ring_me, personal_assistant, a receptionist, a menu, a queue, voicemail, busy, or decline. An optional closed target uses the opening hours. A shared line, receptionist, menu, or queue needs Business.
| Argument | Type | Description |
|---|---|---|
| number | string | |
| target | string | |
| number_id | string | |
| target_id | string | |
| auto_record | boolean | |
| closed_target | string | |
| time_group_id | string | |
| closed_target_id | string |
{
"type": "object",
"properties": {
"number": {
"type": "string"
},
"target": {
"type": "string"
},
"number_id": {
"type": "string"
},
"target_id": {
"type": "string"
},
"auto_record": {
"type": "boolean"
},
"closed_target": {
"type": "string"
},
"time_group_id": {
"type": "string"
},
"closed_target_id": {
"type": "string"
}
},
"additionalProperties": false
}Sends Widely a note about a missing capability, a complaint, or a use case to build. No account is required. reply_url, when it is https, receives each desk reply. Returns conversation_id. Passing that id on a later request adds to the same thread.
| Argument | Type | Description |
|---|---|---|
| kind | string | |
| text* | string | |
| title | string | |
| reply_url | string | Public https URL that receives each reply. |
| conversation_id | string | Continue this thread instead of opening a new one. |
{
"type": "object",
"required": [
"text"
],
"properties": {
"kind": {
"enum": [
"request",
"complaint",
"use_case",
"other"
],
"type": "string"
},
"text": {
"type": "string"
},
"title": {
"type": "string"
},
"reply_url": {
"type": "string",
"description": "Public https URL that receives each reply."
},
"conversation_id": {
"type": "string",
"description": "Continue this thread instead of opening a new one."
}
},
"additionalProperties": false
}Sets the https URL that receives call.started, call.ended, and speak.completed for this seat. events chooses which of those names to receive. Omitting events receives all three. An empty webhook_url stops delivery.
| Argument | Type | Description |
|---|---|---|
| events | array | Names to receive. Omit or empty for all of them. |
| webhook_url | string | Public https URL, or empty to stop. |
{
"type": "object",
"properties": {
"events": {
"type": "array",
"items": {
"enum": [
"call.started",
"call.ended",
"speak.completed"
],
"type": "string"
},
"description": "Names to receive. Omit or empty for all of them."
},
"webhook_url": {
"type": "string",
"description": "Public https URL, or empty to stop."
}
},
"additionalProperties": false
}Returns the UK shared Always-forward destination and the dial code. No sign-in.
No arguments.
{
"type": "object",
"properties": {},
"additionalProperties": false
}Points a verified number at a business number on this seat, or stops forwarding when forward_to is empty. Pro plan.
| Argument | Type | Description |
|---|---|---|
| forward_to | string | A business number on this seat, or empty to stop. |
| identity_id | string |
{
"type": "object",
"properties": {
"forward_to": {
"type": "string",
"description": "A business number on this seat, or empty to stop."
},
"identity_id": {
"type": "string"
}
},
"additionalProperties": false
}Pause, resume, choose who can see the WhatsApp chats, or set the webhook that answers first. Setting a webhook returns the signing secret once.
| Argument | Type | Description |
|---|---|---|
| pause | boolean | |
| did_id* | string | |
| monitor_ids | array | |
| webhook_url | string | |
| clear_webhook | boolean |
{
"type": "object",
"required": [
"did_id"
],
"properties": {
"pause": {
"type": "boolean"
},
"did_id": {
"type": "string"
},
"monitor_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"webhook_url": {
"type": "string"
},
"clear_webhook": {
"type": "boolean"
}
},
"additionalProperties": false
}Creates or edits a timezone-aware opening-hours schedule and optionally attaches it to an AI receptionist. Informational receptionist hours do not change DID routing. day is 0 for Monday through 6 for Sunday; start and end are HH:MM. Date-bounded is_closed windows are exceptions.
| Argument | Type | Description |
|---|---|---|
| id | string | |
| name | string | |
| windows | array | |
| timezone | string | |
| ivr_config_id | string |
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"windows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"day": {
"type": "integer",
"maximum": 6,
"minimum": 0
},
"end": {
"type": "string",
"description": "HH:MM"
},
"start": {
"type": "string",
"description": "HH:MM"
},
"date_end": {
"type": "string",
"description": "Optional ISO date."
},
"is_closed": {
"type": "boolean"
},
"date_start": {
"type": "string",
"description": "Optional ISO date."
}
},
"additionalProperties": false
}
},
"timezone": {
"type": "string"
},
"ivr_config_id": {
"type": "string"
}
},
"additionalProperties": false
}Creates or edits a press-1 menu. The account owner needs Business. A key can ring a person, ring a queue, or send the caller to an AI receptionist. A direct person target and every queue agent also need Business.
| Argument | Type | Description |
|---|---|---|
| id | string | |
| keys | array | Press-1 choices. Sending keys replaces the menu's choices. |
| name | string | |
| enabled | boolean | |
| greeting | string |
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"keys": {
"type": "array",
"items": {
"type": "object",
"required": [
"digit",
"target"
],
"properties": {
"digit": {
"type": "string",
"description": "Key the caller presses, such as 1."
},
"target": {
"enum": [
"user",
"queue",
"ai_receptionist"
],
"type": "string",
"description": "user rings a person. queue rings a queue. ai_receptionist sends the caller to an AI receptionist."
},
"queue_id": {
"type": "string",
"description": "Queue on this account when target is queue."
},
"receptionist_id": {
"type": "string",
"description": "AI receptionist on this account when target is ai_receptionist."
},
"consumer_user_id": {
"type": "string",
"description": "Person on this account when target is user."
}
},
"additionalProperties": false
},
"description": "Press-1 choices. Sending keys replaces the menu's choices."
},
"name": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"greeting": {
"type": "string"
}
},
"additionalProperties": false
}Creates or edits a queue. The account owner and every queue member need Business. A queue rings only members who are signed in and available.
| Argument | Type | Description |
|---|---|---|
| id | string | |
| name | string | |
| overflow | string | |
| strategy | string | |
| member_ids | array | |
| auto_record | boolean | |
| max_wait_seconds | integer |
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"overflow": {
"enum": [
"voicemail",
"other_queue",
"hangup"
],
"type": "string"
},
"strategy": {
"enum": [
"round_robin",
"least_recent",
"priority"
],
"type": "string"
},
"member_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"auto_record": {
"type": "boolean"
},
"max_wait_seconds": {
"type": "integer"
}
},
"additionalProperties": false
}Creates or edits an AI receptionist. The account owner needs Business. It speaks with the caller and does not transfer the live conversation to a person.
| Argument | Type | Description |
|---|---|---|
| id | string | |
| name | string | |
| voice | string | Voice the receptionist speaks with: one of alloy, ash, ballad, cedar, coral, echo, marin, sage, shimmer, verse (default marin), or a custom voice id made in the Widely app, which starts with voice_. Any other value is rejected. |
| enabled | boolean | |
| greeting | string | |
| knowledge | string | |
| languages | array | |
| description | string | |
| default_language | string |
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"voice": {
"type": "string",
"pattern": "^(?:alloy|ash|ballad|cedar|coral|echo|marin|sage|shimmer|verse|voice_[A-Za-z0-9_-]+)$",
"description": "Voice the receptionist speaks with: one of alloy, ash, ballad, cedar, coral, echo, marin, sage, shimmer, verse (default marin), or a custom voice id made in the Widely app, which starts with voice_. Any other value is rejected."
},
"enabled": {
"type": "boolean"
},
"greeting": {
"type": "string"
},
"knowledge": {
"type": "string"
},
"languages": {
"type": "array",
"items": {
"type": "string"
}
},
"description": {
"type": "string"
},
"default_language": {
"type": "string"
}
},
"additionalProperties": false
}Adds or revises a knowledge entry for one receptionist. The next WhatsApp reply and the next phone call both use it.
| Argument | Type | Description |
|---|---|---|
| id | string | |
| body* | string | |
| data | object | |
| title* | string | |
| category | string | |
| ivr_config_id* | string |
{
"type": "object",
"required": [
"ivr_config_id",
"title",
"body"
],
"properties": {
"id": {
"type": "string"
},
"body": {
"type": "string"
},
"data": {
"type": "object"
},
"title": {
"type": "string"
},
"category": {
"enum": [
"service",
"pricing",
"payment",
"inventory",
"policy",
"returns",
"donation",
"faq",
"escalation",
"custom"
],
"type": "string"
},
"ivr_config_id": {
"type": "string"
}
},
"additionalProperties": false
}Stores a business address plus directions, parking, public transport, accessibility, location contacts, coordinates, and timezone.
| Argument | Type | Description |
|---|---|---|
| id | string | |
| city | string | |
| name | string | |
| string | ||
| phone | string | |
| region | string | |
| address | string | |
| parking | string | |
| latitude | number | |
| timezone | string | |
| longitude | number | |
| directions |
Creates or edits the business identity, IANA timezone, contact details, and human-escalation instructions used on phone and WhatsApp.
| Argument | Type | Description |
|---|---|---|
| string | ||
| phone | string | |
| website | string | |
| timezone | string | IANA timezone such as Asia/Jerusalem. |
| is_active | boolean | |
| business_name | string | |
| ivr_config_id* | string | |
| escalation_instructions | string |
{
"type": "object",
"required": [
"ivr_config_id"
],
"properties": {
"email": {
"type": "string"
},
"phone": {
"type": "string"
},
"website": {
"type": "string"
},
"timezone": {
"type": "string",
"description": "IANA timezone such as Asia/Jerusalem."
},
"is_active": {
"type": "boolean"
},
"business_name": {
"type": "string"
},
"ivr_config_id": {
"type": "string"
},
"escalation_instructions": {
"type": "string"
}
},
"additionalProperties": false
}| if_unknown |
| string |
| What to do when asked something the brief does not cover. |
| callee_name* | string | Who you are calling, e.g. 'FedEx UK Import Clearance' or 'Dr Cohen's clinic'. |
| destination* | string | Number to call, E.164 (+44…, +972…, +1…) or local. Emergency and premium-rate numbers are refused. |
| schedule_at | string | When to call, ISO date-time, at most 14 days ahead. Omit it to call now. |
| time_window | object | Optional calling window, at least 10 minutes long and within 14 days. The call is placed inside it. |
| connect_user | boolean | When true, the assistant asks the callee to hold at the end, rings the user's phones into the call, and leaves. |
| on_behalf_of* | object | Who the call is for. person is required. |
| opening_line | string | Optional. What to say first, after the assistant introduces itself and plays the mandatory notice. |
| facts_to_give | array | Facts the assistant may give. Card numbers, CVVs, PINs and passwords are refused. |
| assistant_name | string | Optional. The name the assistant uses on this call instead of the AI assistant settings name. |
| save_as_default | boolean | With assistant_name, also save it as the default name in Widely AI assistant settings. |
| client_reference | string | Your own reference. |
| facts_to_collect | array | Questions to ask and the information to bring back. |
| purpose_category* | string | Kind of call. Marketing, sales, surveys, debt collection, political and fundraising calls are refused. |
| success_criteria* | array | How to tell the call worked, e.g. 'they confirm the delivery date'. |
| voicemail_message | string | Optional. If absent, the assistant leaves a short message from the goal and on_behalf_of, with no sensitive facts. |
| callee_is_business | boolean | Optional. True when the callee is a business. |
| caller_identity_id | string | Optional. You may set it. If you omit it, Widely picks the caller ID. If you set it, it must be an identity_id from list_identities, one of the user's own. Never invent another number. |
| allowed_commitments | array | The only things the assistant may agree to, e.g. 'accept any slot Tue–Thu after 14:00'. For anything else it says it will check and come back, and lists it in the report. Payments, contracts and cancellations are never allowed. |
{
"type": "object",
"required": [
"destination",
"callee_name",
"goal",
"on_behalf_of",
"purpose_category",
"success_criteria"
],
"properties": {
"goal": {
"type": "string",
"maxLength": 500,
"minLength": 8,
"description": "The outcome you want, in one or two sentences."
},
"limits": {
"type": "object",
"properties": {
"retry": {
"type": "object",
"properties": {
"gap_minutes": {
"type": "integer",
"minimum": 0
},
"on_busy_or_no_answer": {
"type": "integer",
"default": 0,
"maximum": 3,
"minimum": 0
}
},
"additionalProperties": false
},
"max_cost": {
"type": "number",
"minimum": 0
},
"max_ivr_minutes": {
"type": "integer",
"default": 6,
"maximum": 15,
"minimum": 1
},
"max_call_minutes": {
"type": "integer",
"default": 30,
"maximum": 120,
"minimum": 1
},
"max_hold_minutes": {
"type": "integer",
"default": 20,
"maximum": 90,
"minimum": 0
}
},
"additionalProperties": false
},
"callback": {
"type": "object",
"properties": {
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"webhook_url": {
"type": "string",
"format": "uri",
"description": "https URL for task events."
}
},
"additionalProperties": false
},
"language": {
"type": "string",
"maxLength": 40,
"description": "BCP-47 such as en-GB or he-IL, or auto-from-seat."
},
"forbidden": {
"type": "array",
"items": {
"type": "string",
"maxLength": 200
},
"maxItems": 10,
"description": "Things the assistant must not say or agree to."
},
"ivr_hints": {
"type": "array",
"items": {
"type": "string",
"maxLength": 200
},
"maxItems": 20,
"description": "Phone menu hints, e.g. 'choose imports'."
},
"voicemail": {
"enum": [
"leave_message",
"hang_up_and_retry",
"hang_up"
],
"type": "string",
"default": "leave_message",
"description": "On voicemail: leave_message (default), hang_up_and_retry (uses limits.retry), or hang_up."
},
"escalation": {
"type": "object",
"properties": {
"mode": {
"enum": [
"never",
"on_request",
"on_human",
"on_blocker"
],
"type": "string",
"default": "on_blocker"
},
"notify": {
"enum": [
"app",
"whatsapp",
"both"
],
"type": "string",
"default": "app"
},
"blockers": {
"type": "array",
"items": {
"enum": [
"verification_failed",
"asks_for_account_holder",
"payment_requested",
"legal_or_dispute",
"callee_requests_human",
"unknown_fact_needed"
],
"type": "string"
}
},
"ring_user_after_seconds": {
"type": "integer",
"default": 60,
"maximum": 600,
"minimum": 0
}
},
"additionalProperties": false
},
"if_unknown": {
"enum": [
"say_will_check_back",
"escalate",
"end_politely"
],
"type": "string",
"default": "say_will_check_back",
"description": "What to do when asked something the brief does not cover."
},
"callee_name": {
"type": "string",
"maxLength": 120,
"description": "Who you are calling, e.g. 'FedEx UK Import Clearance' or 'Dr Cohen's clinic'."
},
"destination": {
"type": "string",
"maxLength": 32,
"description": "Number to call, E.164 (+44…, +972…, +1…) or local. Emergency and premium-rate numbers are refused."
},
"schedule_at": {
"type": "string",
"format": "date-time",
"description": "When to call, ISO date-time, at most 14 days ahead. Omit it to call now."
},
"time_window": {
"type": "object",
"required": [
"not_before",
"not_after"
],
"properties": {
"not_after": {
"type": "string",
"format": "date-time",
"description": "ISO date-time with offset."
},
"not_before": {
"type": "string",
"format": "date-time",
"description": "ISO date-time with offset."
}
},
"description": "Optional calling window, at least 10 minutes long and within 14 days. The call is placed inside it.",
"additionalProperties": false
},
"connect_user": {
"type": "boolean",
"default": false,
"description": "When true, the assistant asks the callee to hold at the end, rings the user's phones into the call, and leaves."
},
"on_behalf_of": {
"type": "object",
"required": [
"person"
],
"properties": {
"person": {
"type": "string",
"maxLength": 120,
"description": "Name of the person the call is for."
},
"company": {
"type": "string",
"maxLength": 120,
"description": "Company, if the call is for a business."
},
"relationship": {
"type": "string",
"maxLength": 120,
"description": "e.g. 'account holder', 'director', 'parent'."
}
},
"description": "Who the call is for. person is required.",
"additionalProperties": false
},
"opening_line": {
"type": "string",
"maxLength": 200,
"description": "Optional. What to say first, after the assistant introduces itself and plays the mandatory notice."
},
"facts_to_give": {
"type": "array",
"items": {
"type": "object",
"required": [
"key",
"value"
],
"properties": {
"key": {
"type": "string",
"maxLength": 80,
"description": "Short label, e.g. 'order_number'."
},
"value": {
"type": "string",
"maxLength": 300,
"description": "The fact."
},
"disclose": {
"enum": [
"freely",
"if_asked",
"only_to_verified_human",
"never"
],
"type": "string",
"default": "if_asked"
}
},
"additionalProperties": false
},
"maxItems": 30,
"description": "Facts the assistant may give. Card numbers, CVVs, PINs and passwords are refused."
},
"assistant_name": {
"type": "string",
"maxLength": 40,
"description": "Optional. The name the assistant uses on this call instead of the AI assistant settings name."
},
"save_as_default": {
"type": "boolean",
"default": false,
"description": "With assistant_name, also save it as the default name in Widely AI assistant settings."
},
"client_reference": {
"type": "string",
"maxLength": 100,
"description": "Your own reference."
},
"facts_to_collect": {
"type": "array",
"items": {
"type": "object",
"required": [
"key",
"description"
],
"properties": {
"key": {
"type": "string",
"pattern": "^[a-z0-9_]{1,40}$"
},
"type": {
"enum": [
"string",
"number",
"date",
"boolean",
"money",
"reference"
],
"type": "string",
"default": "string"
},
"required": {
"type": "boolean",
"default": true
},
"description": {
"type": "string",
"maxLength": 300,
"description": "The question to ask or the information needed."
},
"confirm_back": {
"type": "boolean",
"default": true
}
},
"additionalProperties": false
},
"maxItems": 20,
"description": "Questions to ask and the information to bring back."
},
"purpose_category": {
"enum": [
"service_enquiry",
"account_admin",
"booking",
"logistics",
"complaint",
"other_non_marketing"
],
"type": "string",
"description": "Kind of call. Marketing, sales, surveys, debt collection, political and fundraising calls are refused."
},
"success_criteria": {
"type": "array",
"items": {
"type": "string",
"maxLength": 200
},
"maxItems": 10,
"minItems": 1,
"description": "How to tell the call worked, e.g. 'they confirm the delivery date'."
},
"voicemail_message": {
"type": "string",
"maxLength": 300,
"description": "Optional. If absent, the assistant leaves a short message from the goal and on_behalf_of, with no sensitive facts."
},
"callee_is_business": {
"type": "boolean",
"description": "Optional. True when the callee is a business."
},
"caller_identity_id": {
"type": "string",
"maxLength": 64,
"description": "Optional. You may set it. If you omit it, Widely picks the caller ID. If you set it, it must be an identity_id from list_identities, one of the user's own. Never invent another number."
},
"allowed_commitments": {
"type": "array",
"items": {
"type": "string",
"maxLength": 200
},
"maxItems": 10,
"description": "The only things the assistant may agree to, e.g. 'accept any slot Tue–Thu after 14:00'. For anything else it says it will check and come back, and lists it in the report. Payments, contracts and cancellations are never allowed."
}
},
"additionalProperties": false
}| if_unknown |
| string |
| What to do when asked something the brief does not cover. |
| callee_name* | string | Who you are calling, e.g. 'FedEx UK Import Clearance' or 'Dr Cohen's clinic'. |
| destination* | string | Number to call, E.164 (+44…, +972…, +1…) or local. Emergency and premium-rate numbers are refused. |
| schedule_at | string | When to call, ISO date-time, at most 14 days ahead. Omit it to call now. |
| time_window | object | Optional calling window, at least 10 minutes long and within 14 days. The call is placed inside it. |
| connect_user | boolean | When true, the assistant asks the callee to hold at the end, rings the user's phones into the call, and leaves. |
| on_behalf_of* | object | Who the call is for. person is required. |
| opening_line | string | Optional. What to say first, after the assistant introduces itself and plays the mandatory notice. |
| facts_to_give | array | Facts the assistant may give. Card numbers, CVVs, PINs and passwords are refused. |
| assistant_name | string | Optional. The name the assistant uses on this call instead of the AI assistant settings name. |
| save_as_default | boolean | With assistant_name, also save it as the default name in Widely AI assistant settings. |
| client_reference | string | Your own reference. |
| facts_to_collect | array | Questions to ask and the information to bring back. |
| purpose_category* | string | Kind of call. Marketing, sales, surveys, debt collection, political and fundraising calls are refused. |
| success_criteria* | array | How to tell the call worked, e.g. 'they confirm the delivery date'. |
| voicemail_message | string | Optional. If absent, the assistant leaves a short message from the goal and on_behalf_of, with no sensitive facts. |
| callee_is_business | boolean | Optional. True when the callee is a business. |
| caller_identity_id | string | Optional. You may set it. If you omit it, Widely picks the caller ID. If you set it, it must be an identity_id from list_identities, one of the user's own. Never invent another number. |
| allowed_commitments | array | The only things the assistant may agree to, e.g. 'accept any slot Tue–Thu after 14:00'. For anything else it says it will check and come back, and lists it in the report. Payments, contracts and cancellations are never allowed. |
{
"type": "object",
"required": [
"destination",
"callee_name",
"goal",
"on_behalf_of",
"purpose_category",
"success_criteria"
],
"properties": {
"goal": {
"type": "string",
"maxLength": 500,
"minLength": 8,
"description": "The outcome you want, in one or two sentences."
},
"limits": {
"type": "object",
"properties": {
"retry": {
"type": "object",
"properties": {
"gap_minutes": {
"type": "integer",
"minimum": 0
},
"on_busy_or_no_answer": {
"type": "integer",
"default": 0,
"maximum": 3,
"minimum": 0
}
},
"additionalProperties": false
},
"max_cost": {
"type": "number",
"minimum": 0
},
"max_ivr_minutes": {
"type": "integer",
"default": 6,
"maximum": 15,
"minimum": 1
},
"max_call_minutes": {
"type": "integer",
"default": 30,
"maximum": 120,
"minimum": 1
},
"max_hold_minutes": {
"type": "integer",
"default": 20,
"maximum": 90,
"minimum": 0
}
},
"additionalProperties": false
},
"callback": {
"type": "object",
"properties": {
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"webhook_url": {
"type": "string",
"format": "uri",
"description": "https URL for task events."
}
},
"additionalProperties": false
},
"language": {
"type": "string",
"maxLength": 40,
"description": "BCP-47 such as en-GB or he-IL, or auto-from-seat."
},
"forbidden": {
"type": "array",
"items": {
"type": "string",
"maxLength": 200
},
"maxItems": 10,
"description": "Things the assistant must not say or agree to."
},
"ivr_hints": {
"type": "array",
"items": {
"type": "string",
"maxLength": 200
},
"maxItems": 20,
"description": "Phone menu hints, e.g. 'choose imports'."
},
"voicemail": {
"enum": [
"leave_message",
"hang_up_and_retry",
"hang_up"
],
"type": "string",
"default": "leave_message",
"description": "On voicemail: leave_message (default), hang_up_and_retry (uses limits.retry), or hang_up."
},
"escalation": {
"type": "object",
"properties": {
"mode": {
"enum": [
"never",
"on_request",
"on_human",
"on_blocker"
],
"type": "string",
"default": "on_blocker"
},
"notify": {
"enum": [
"app",
"whatsapp",
"both"
],
"type": "string",
"default": "app"
},
"blockers": {
"type": "array",
"items": {
"enum": [
"verification_failed",
"asks_for_account_holder",
"payment_requested",
"legal_or_dispute",
"callee_requests_human",
"unknown_fact_needed"
],
"type": "string"
}
},
"ring_user_after_seconds": {
"type": "integer",
"default": 60,
"maximum": 600,
"minimum": 0
}
},
"additionalProperties": false
},
"if_unknown": {
"enum": [
"say_will_check_back",
"escalate",
"end_politely"
],
"type": "string",
"default": "say_will_check_back",
"description": "What to do when asked something the brief does not cover."
},
"callee_name": {
"type": "string",
"maxLength": 120,
"description": "Who you are calling, e.g. 'FedEx UK Import Clearance' or 'Dr Cohen's clinic'."
},
"destination": {
"type": "string",
"maxLength": 32,
"description": "Number to call, E.164 (+44…, +972…, +1…) or local. Emergency and premium-rate numbers are refused."
},
"schedule_at": {
"type": "string",
"format": "date-time",
"description": "When to call, ISO date-time, at most 14 days ahead. Omit it to call now."
},
"time_window": {
"type": "object",
"required": [
"not_before",
"not_after"
],
"properties": {
"not_after": {
"type": "string",
"format": "date-time",
"description": "ISO date-time with offset."
},
"not_before": {
"type": "string",
"format": "date-time",
"description": "ISO date-time with offset."
}
},
"description": "Optional calling window, at least 10 minutes long and within 14 days. The call is placed inside it.",
"additionalProperties": false
},
"connect_user": {
"type": "boolean",
"default": false,
"description": "When true, the assistant asks the callee to hold at the end, rings the user's phones into the call, and leaves."
},
"on_behalf_of": {
"type": "object",
"required": [
"person"
],
"properties": {
"person": {
"type": "string",
"maxLength": 120,
"description": "Name of the person the call is for."
},
"company": {
"type": "string",
"maxLength": 120,
"description": "Company, if the call is for a business."
},
"relationship": {
"type": "string",
"maxLength": 120,
"description": "e.g. 'account holder', 'director', 'parent'."
}
},
"description": "Who the call is for. person is required.",
"additionalProperties": false
},
"opening_line": {
"type": "string",
"maxLength": 200,
"description": "Optional. What to say first, after the assistant introduces itself and plays the mandatory notice."
},
"facts_to_give": {
"type": "array",
"items": {
"type": "object",
"required": [
"key",
"value"
],
"properties": {
"key": {
"type": "string",
"maxLength": 80,
"description": "Short label, e.g. 'order_number'."
},
"value": {
"type": "string",
"maxLength": 300,
"description": "The fact."
},
"disclose": {
"enum": [
"freely",
"if_asked",
"only_to_verified_human",
"never"
],
"type": "string",
"default": "if_asked"
}
},
"additionalProperties": false
},
"maxItems": 30,
"description": "Facts the assistant may give. Card numbers, CVVs, PINs and passwords are refused."
},
"assistant_name": {
"type": "string",
"maxLength": 40,
"description": "Optional. The name the assistant uses on this call instead of the AI assistant settings name."
},
"save_as_default": {
"type": "boolean",
"default": false,
"description": "With assistant_name, also save it as the default name in Widely AI assistant settings."
},
"client_reference": {
"type": "string",
"maxLength": 100,
"description": "Your own reference."
},
"facts_to_collect": {
"type": "array",
"items": {
"type": "object",
"required": [
"key",
"description"
],
"properties": {
"key": {
"type": "string",
"pattern": "^[a-z0-9_]{1,40}$"
},
"type": {
"enum": [
"string",
"number",
"date",
"boolean",
"money",
"reference"
],
"type": "string",
"default": "string"
},
"required": {
"type": "boolean",
"default": true
},
"description": {
"type": "string",
"maxLength": 300,
"description": "The question to ask or the information needed."
},
"confirm_back": {
"type": "boolean",
"default": true
}
},
"additionalProperties": false
},
"maxItems": 20,
"description": "Questions to ask and the information to bring back."
},
"purpose_category": {
"enum": [
"service_enquiry",
"account_admin",
"booking",
"logistics",
"complaint",
"other_non_marketing"
],
"type": "string",
"description": "Kind of call. Marketing, sales, surveys, debt collection, political and fundraising calls are refused."
},
"success_criteria": {
"type": "array",
"items": {
"type": "string",
"maxLength": 200
},
"maxItems": 10,
"minItems": 1,
"description": "How to tell the call worked, e.g. 'they confirm the delivery date'."
},
"voicemail_message": {
"type": "string",
"maxLength": 300,
"description": "Optional. If absent, the assistant leaves a short message from the goal and on_behalf_of, with no sensitive facts."
},
"callee_is_business": {
"type": "boolean",
"description": "Optional. True when the callee is a business."
},
"caller_identity_id": {
"type": "string",
"maxLength": 64,
"description": "Optional. You may set it. If you omit it, Widely picks the caller ID. If you set it, it must be an identity_id from list_identities, one of the user's own. Never invent another number."
},
"allowed_commitments": {
"type": "array",
"items": {
"type": "string",
"maxLength": 200
},
"maxItems": 10,
"description": "The only things the assistant may agree to, e.g. 'accept any slot Tue–Thu after 14:00'. For anything else it says it will check and come back, and lists it in the report. Payments, contracts and cancellations are never allowed."
}
},
"additionalProperties": false
}{
"type": "object",
"properties": {
"days": {
"type": "integer",
"maximum": 3650,
"minimum": 1,
"description": "Look back this many days (default 30)."
},
"line": {
"enum": [
"sip_extension",
"business_number",
"trunk"
],
"type": "string"
},
"limit": {
"type": "integer",
"maximum": 50,
"minimum": 1,
"description": "Max rows to return."
},
"query": {
"type": "string",
"description": "Words from a stored transcript. Pro."
},
"since": {
"type": "string",
"description": "ISO 8601 start (inclusive)."
},
"until": {
"type": "string",
"description": "ISO 8601 end (exclusive)."
},
"number": {
"type": "string",
"description": "Phone number or trailing digits."
},
"contact": {
"type": "string",
"description": "Saved contact name to match."
},
"direction": {
"enum": [
"inbound",
"outbound"
],
"type": "string"
},
"missed_only": {
"type": "boolean"
}
},
"additionalProperties": false
}| string |
| is_primary | boolean |
| postal_code | string |
| country_code | string |
| accessibility | string |
| ivr_config_id* | string |
| public_transport | string |
{
"type": "object",
"required": [
"ivr_config_id"
],
"properties": {
"id": {
"type": "string"
},
"city": {
"type": "string"
},
"name": {
"type": "string"
},
"email": {
"type": "string"
},
"phone": {
"type": "string"
},
"region": {
"type": "string"
},
"address": {
"type": "string"
},
"parking": {
"type": "string"
},
"latitude": {
"type": "number"
},
"timezone": {
"type": "string"
},
"longitude": {
"type": "number"
},
"directions": {
"type": "string"
},
"is_primary": {
"type": "boolean"
},
"postal_code": {
"type": "string"
},
"country_code": {
"type": "string"
},
"accessibility": {
"type": "string"
},
"ivr_config_id": {
"type": "string"
},
"public_transport": {
"type": "string"
}
},
"additionalProperties": false
}