{ "openapi": "3.1.0", "info": { "title": "Vocenya API", "version": "1.0.0", "description": "The Vocenya API lets you read your calls, leads, bookings and chats, add leads, queue compliant\noutbound AI calls, manage your Do Not Call list and subscribe to webhooks.\n\nAuthenticate every request with an organization API key, created by an account owner on the\nDevelopers page of the portal: `Authorization: Bearer vk_live_...`. Each key carries scopes\n(for example `leads:read`), and requests are rate limited per key (120 per minute by default).\n\nLists are newest first and use cursor pagination: pass `per_page` (1 to 100, default 25) and\nthe `meta.next_cursor` of the previous page as `cursor`. Times are ISO 8601.\n\nErrors return `{\"message\": \"...\", \"code\": \"...\"}` with a matching HTTP status; validation\nerrors (422) add `errors` per field. HIPAA-mode accounts never receive call transcripts,\nAI summaries, lead reasons or chat messages, and their webhooks carry ids only.\n\nPrefer to work with an AI assistant? The same data is available through the Vocenya MCP\nserver at `\/mcp\/platform`, with the same keys and scopes." }, "servers": [ { "url": "https:\/\/vocenya.com\/api\/public\/v1", "description": "Production" } ], "tags": [ { "name": "Account", "description": "The account and key behind the request." }, { "name": "Calls", "description": "Phone calls your AI receptionist, GH Live agents and team handled. Needs `calls:read`." }, { "name": "Leads", "description": "People who called, chatted or filled in a form. Reading needs `leads:read`, creating needs `leads:write` (plus `outbound:write` to request an AI callback)." }, { "name": "Bookings", "description": "Appointments the AI booked into your calendar or field-service software. Needs `bookings:read`." }, { "name": "Outbound calls", "description": "Have the AI call someone who agreed to AI calls. Needs `outbound:write`." }, { "name": "Do Not Call", "description": "Numbers your AI never calls. Reading needs `dnc:read`, changes need `dnc:write`. GH's own list is always enforced but not listed." }, { "name": "Blocked callers", "description": "Numbers and prefixes whose inbound calls are turned away before your receptionist answers (spam, robocallers). Reading needs `dnc:read`, changes need `dnc:write`." }, { "name": "Chats", "description": "Chats on your website widget (`channel: web`) and on WhatsApp (`channel: whatsapp`, with the customer's\nnumber in `contact_address`). Reading needs `chats:read`; replying and closing need `chats:write`.\n\nWhatsApp only allows free-form replies within 24 hours of the customer's last message: after that a reply\nis refused with `whatsapp_window_closed` (`reply_window_open` tells you beforehand).\n\nReplies you send show in the visitor's widget straight away, from \"Team\", exactly like a reply typed in\nthe portal inbox. Replying to a chat the AI is answering takes it over (status `with_owner`), so the AI\nstops answering. To build a bot or route chats to your own help desk, subscribe a webhook endpoint to\n`chat.message.created` and answer with `POST \/chats\/{chat}\/messages`; skip messages with `via_api: true`,\nwhich are your own." }, { "name": "Webhooks", "description": "Get events pushed to your HTTPS endpoint instead of polling. Needs `webhooks:manage`. Subscribing\nan endpoint to an event also needs that record's read scope: `lead.created` needs `leads:read`,\n`call.completed` needs `calls:read`, `booking.created` needs `bookings:read`,\n`outbound_call.completed` needs `outbound:write`, every `chat.*` event needs `chats:read`, and\n`chat.lead_captured` also needs `leads:read`.\n\nEach delivery is a `POST` with a JSON body `{\"id\", \"type\", \"created_at\", \"data\"}` and these headers:\n`Vocenya-Event` (the event type), `Vocenya-Delivery` (the event id; use it to ignore duplicates) and\n`Vocenya-Signature: t=,v1=`. To verify, compute HMAC-SHA256 of `\".\"`\nwith your endpoint's secret, compare it to `v1` in constant time, and reject timestamps more than\n5 minutes old.\n\nAnswer with any 2xx within 10 seconds. Anything else is retried with backoff (1 min, 5 min, 15 min,\n1 h, 3 h, 6 h, 12 h) for up to 8 attempts. Payloads carry ids, statuses, times and contact\ndetails, never conversation content, except `chat.message.created`, which carries the message so\nyour system can answer it. HIPAA-mode accounts get ids only. Fetch the full record from the API\nwhen you need more.\n\nEvents: `lead.created`, `call.completed`, `booking.created`, `outbound_call.completed`, and for\nwebsite live chat `chat.started`, `chat.message.created`, `chat.lead_captured`,\n`chat.handoff_requested`, `chat.handed_off` and `chat.closed`.\n\nLive chat events share a `chat` object: `{\"id\", \"status\", \"page_url\", \"handed_off_at\", \"closed_at\",\n\"created_at\"}`. `chat.message.created` adds `message`: `{\"id\", \"sender\", \"role\", \"author\", \"body\",\n\"via_api\", \"created_at\"}`, where `sender` is `visitor`, `ai`, `agent`, `owner` or `system` and `role`\nis what the widget shows (`visitor`, `ai`, `team` or `system`); skip `via_api: true`, your own\nreplies. `chat.lead_captured` adds `lead` (the `lead.created` fields). `chat.handoff_requested`\nadds `requested_by` (`visitor` or `ai`) when a person is asked for; `chat.handed_off` also fires\nwhen your team takes a chat over by replying. `chat.closed` adds `chat.lead_id` and\n`chat.message_count`. Example `chat.message.created`:\n\n```json\n{\"id\": \"9f0c...\", \"type\": \"chat.message.created\", \"created_at\": \"2026-10-02T14:03:30+00:00\",\n \"data\": {\"chat\": {\"id\": 205, \"status\": \"ai\", \"page_url\": \"https:\/\/www.example.com\/contact\",\n \"handed_off_at\": null, \"closed_at\": null, \"created_at\": \"2026-10-02T14:03:11+00:00\"},\n \"message\": {\"id\": 4410, \"sender\": \"visitor\", \"role\": \"visitor\", \"author\": \"Visitor\",\n \"body\": \"Hi, do you have any openings this week?\", \"via_api\": false,\n \"created_at\": \"2026-10-02T14:03:30+00:00\"}}}\n```\n\nThe same event for a HIPAA-mode account: `{\"chat\": {\"id\": 205}, \"message\": {\"id\": 4410}}`." } ], "security": [ { "apiKey": [] } ], "paths": { "\/me": { "get": { "operationId": "getMe", "description": "Check a key and see which account it belongs to, what it may do and whether it is a live or a\ntest key. Needs no scope.", "summary": "Get the current key", "tags": [ "Account" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "livemode": { "type": "boolean", "description": "`false` when the key is a test key (`vk_test_`): every request then reads and writes test data only." }, "organization": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string", "examples": [ "Rivera Plumbing" ] }, "hipaa_mode": { "type": "boolean", "description": "When true, transcripts, summaries, lead reasons and chat messages are never returned, and webhooks carry ids only." }, "timezone": { "type": "string", "examples": [ "America\/Chicago" ] } }, "required": [ "id", "name", "hipaa_mode", "timezone" ] }, "api_key": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string", "examples": [ "Zapier" ] }, "prefix": { "type": "string", "examples": [ "vk_live_a1b2c3d4" ] }, "mode": { "type": "string", "description": "`live` or `test`.", "enum": [ "live", "test" ] }, "scopes": { "type": "array", "examples": [ [ "leads:read", "leads:write" ] ], "items": { "type": "string" } }, "expires_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "prefix", "mode", "scopes", "expires_at" ] } }, "required": [ "livemode", "organization", "api_key" ] } }, "required": [ "data" ] } } } }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Missing, invalid, expired or revoked API key. Send it as \"Authorization: Bearer vk_live_...\" (or vk_test_... for test mode)." ] }, "code": { "type": "string", "examples": [ "unauthenticated" ] } }, "required": [ "message", "code" ] } } } }, "429": { "description": "Too many requests for this key. Wait for the `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Too Many Attempts." ] }, "code": { "type": "string", "examples": [ "rate_limited" ] } }, "required": [ "message", "code" ] } } } } } } }, "\/calls": { "get": { "operationId": "listCalls", "description": "Your calls, newest first.", "summary": "List calls", "tags": [ "Calls" ], "parameters": [ { "name": "direction", "in": "query", "schema": { "$ref": "#\/components\/schemas\/CallDirection" } }, { "name": "status", "in": "query", "schema": { "$ref": "#\/components\/schemas\/CallStatus" } }, { "name": "since", "in": "query", "description": "Calls that started at or after this time (ISO 8601).", "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "description": "Calls that started before this time (ISO 8601).", "schema": { "type": "string", "format": "date-time" } }, { "name": "spam", "in": "query", "description": "`true` for only spam and blocked calls, `false` to leave them out. Without it, every call is listed.", "schema": { "type": "string", "enum": [ "true", "false", "1", "0" ] } }, { "name": "per_page", "in": "query", "description": "How many items per page, 1 to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "description": "The `meta.next_cursor` (or `meta.prev_cursor`) of the previous page.", "schema": { "type": [ "string", "null" ], "maxLength": 1024 } } ], "responses": { "200": { "description": "Paginated set of `CallResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/CallResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "next_cursor": { "type": [ "string", "null" ], "description": "The \"cursor\" that points to the next set of items." }, "prev_cursor": { "type": [ "string", "null" ], "description": "The \"cursor\" that points to the previous set of items." } }, "required": [ "path", "per_page", "next_cursor", "prev_cursor" ] } }, "required": [ "data", "links", "meta" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Missing, invalid, expired or revoked API key. Send it as \"Authorization: Bearer vk_live_...\" (or vk_test_... for test mode)." ] }, "code": { "type": "string", "examples": [ "unauthenticated" ] } }, "required": [ "message", "code" ] } } } }, "403": { "description": "The key does not have the `calls:read` scope.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "This API key does not have the calls:read scope." ] }, "code": { "type": "string", "examples": [ "missing_scope" ] } }, "required": [ "message", "code" ] } } } }, "429": { "description": "Too many requests for this key. Wait for the `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Too Many Attempts." ] }, "code": { "type": "string", "examples": [ "rate_limited" ] } }, "required": [ "message", "code" ] } } } } } } }, "\/calls\/{call}": { "get": { "operationId": "getCall", "description": "One call with its transcript and the ids of the leads captured on it. HIPAA-mode accounts get\nthe call's ids, numbers, statuses and times only: no summary, handoff summary or transcript.", "summary": "Get a call", "tags": [ "Calls" ], "parameters": [ { "name": "call", "in": "path", "required": true, "description": "The call id.", "schema": { "type": "integer" }, "example": 1042 } ], "responses": { "200": { "description": "`CallResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/CallResource" } }, "required": [ "data" ] } } } }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Missing, invalid, expired or revoked API key. Send it as \"Authorization: Bearer vk_live_...\" (or vk_test_... for test mode)." ] }, "code": { "type": "string", "examples": [ "unauthenticated" ] } }, "required": [ "message", "code" ] } } } }, "403": { "description": "The key does not have the `calls:read` scope.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "This API key does not have the calls:read scope." ] }, "code": { "type": "string", "examples": [ "missing_scope" ] } }, "required": [ "message", "code" ] } } } }, "404": { "description": "No record with that id belongs to your account.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "That record was not found." ] }, "code": { "type": "string", "examples": [ "not_found" ] } }, "required": [ "message", "code" ] } } } }, "429": { "description": "Too many requests for this key. Wait for the `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Too Many Attempts." ] }, "code": { "type": "string", "examples": [ "rate_limited" ] } }, "required": [ "message", "code" ] } } } } } } }, "\/leads": { "get": { "operationId": "listLeads", "description": "Your leads, newest first.", "summary": "List leads", "tags": [ "Leads" ], "parameters": [ { "name": "phone_number", "in": "query", "description": "Leads with this phone number, in any common US format.", "schema": { "type": "string", "maxLength": 32 } }, { "name": "email", "in": "query", "schema": { "type": "string", "format": "email", "maxLength": 255 } }, { "name": "since", "in": "query", "description": "Leads created at or after this time (ISO 8601).", "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "description": "Leads created before this time (ISO 8601).", "schema": { "type": "string", "format": "date-time" } }, { "name": "per_page", "in": "query", "description": "How many items per page, 1 to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "description": "The `meta.next_cursor` (or `meta.prev_cursor`) of the previous page.", "schema": { "type": [ "string", "null" ], "maxLength": 1024 } } ], "responses": { "200": { "description": "Paginated set of `LeadResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/LeadResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "next_cursor": { "type": [ "string", "null" ], "description": "The \"cursor\" that points to the next set of items." }, "prev_cursor": { "type": [ "string", "null" ], "description": "The \"cursor\" that points to the previous set of items." } }, "required": [ "path", "per_page", "next_cursor", "prev_cursor" ] } }, "required": [ "data", "links", "meta" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Missing, invalid, expired or revoked API key. Send it as \"Authorization: Bearer vk_live_...\" (or vk_test_... for test mode)." ] }, "code": { "type": "string", "examples": [ "unauthenticated" ] } }, "required": [ "message", "code" ] } } } }, "403": { "description": "The key does not have the `leads:read` scope.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "This API key does not have the leads:read scope." ] }, "code": { "type": "string", "examples": [ "missing_scope" ] } }, "required": [ "message", "code" ] } } } }, "429": { "description": "Too many requests for this key. Wait for the `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Too Many Attempts." ] }, "code": { "type": "string", "examples": [ "rate_limited" ] } }, "required": [ "message", "code" ] } } } } } }, "post": { "operationId": "createLead", "description": "Add a lead from your own system, for example a form on another site. It shows up in the portal\nand is pushed to your CRM like any other lead.\n\nSend `callback` to have the AI call the person back straight away (speed-to-lead). The key then\nalso needs the `outbound:write` scope. It needs outbound calling switched on, an active Pro plan and an AI receptionist, and is not available\nin HIPAA mode. The call still follows calling hours, Do Not Call lists and daily limits; the\nqueued call is returned as `callback`.", "summary": "Create a lead", "tags": [ "Leads" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/StoreLeadRequest" } } } }, "responses": { "201": { "description": "The lead, and the AI callback when one was requested.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/LeadResource" }, "callback": { "anyOf": [ { "$ref": "#\/components\/schemas\/OutboundCallResource" }, { "type": "null" } ] } }, "required": [ "data", "callback" ] } } } }, "422": { "description": "Validation failed, or a callback was requested but cannot be made (`speed_to_lead_unavailable`, `invalid_number`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message" ] } } } }, "403": { "description": "A `callback` was sent but the key does not have the `outbound:write` scope (`missing_scope`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "message", "code" ] } } } }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Missing, invalid, expired or revoked API key. Send it as \"Authorization: Bearer vk_live_...\" (or vk_test_... for test mode)." ] }, "code": { "type": "string", "examples": [ "unauthenticated" ] } }, "required": [ "message", "code" ] } } } }, "429": { "description": "Too many requests for this key. Wait for the `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Too Many Attempts." ] }, "code": { "type": "string", "examples": [ "rate_limited" ] } }, "required": [ "message", "code" ] } } } } } } }, "\/leads\/{lead}": { "get": { "operationId": "getLead", "summary": "Get a lead", "tags": [ "Leads" ], "parameters": [ { "name": "lead", "in": "path", "required": true, "description": "The lead id.", "schema": { "type": "integer" }, "example": 311 } ], "responses": { "200": { "description": "`LeadResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/LeadResource" } }, "required": [ "data" ] } } } }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Missing, invalid, expired or revoked API key. Send it as \"Authorization: Bearer vk_live_...\" (or vk_test_... for test mode)." ] }, "code": { "type": "string", "examples": [ "unauthenticated" ] } }, "required": [ "message", "code" ] } } } }, "403": { "description": "The key does not have the `leads:read` scope.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "This API key does not have the leads:read scope." ] }, "code": { "type": "string", "examples": [ "missing_scope" ] } }, "required": [ "message", "code" ] } } } }, "404": { "description": "No record with that id belongs to your account.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "That record was not found." ] }, "code": { "type": "string", "examples": [ "not_found" ] } }, "required": [ "message", "code" ] } } } }, "429": { "description": "Too many requests for this key. Wait for the `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Too Many Attempts." ] }, "code": { "type": "string", "examples": [ "rate_limited" ] } }, "required": [ "message", "code" ] } } } } } } }, "\/bookings": { "get": { "operationId": "listBookings", "description": "Appointments the AI booked, most recently booked first. Filter by appointment time.", "summary": "List bookings", "tags": [ "Bookings" ], "parameters": [ { "name": "starts_after", "in": "query", "description": "Appointments starting at or after this time (ISO 8601).", "schema": { "type": "string", "format": "date-time" } }, { "name": "starts_before", "in": "query", "description": "Appointments starting before this time (ISO 8601).", "schema": { "type": "string", "format": "date-time" } }, { "name": "per_page", "in": "query", "description": "How many items per page, 1 to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "description": "The `meta.next_cursor` (or `meta.prev_cursor`) of the previous page.", "schema": { "type": [ "string", "null" ], "maxLength": 1024 } } ], "responses": { "200": { "description": "Paginated set of `BookingResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/BookingResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "next_cursor": { "type": [ "string", "null" ], "description": "The \"cursor\" that points to the next set of items." }, "prev_cursor": { "type": [ "string", "null" ], "description": "The \"cursor\" that points to the previous set of items." } }, "required": [ "path", "per_page", "next_cursor", "prev_cursor" ] } }, "required": [ "data", "links", "meta" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Missing, invalid, expired or revoked API key. Send it as \"Authorization: Bearer vk_live_...\" (or vk_test_... for test mode)." ] }, "code": { "type": "string", "examples": [ "unauthenticated" ] } }, "required": [ "message", "code" ] } } } }, "403": { "description": "The key does not have the `bookings:read` scope.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "This API key does not have the bookings:read scope." ] }, "code": { "type": "string", "examples": [ "missing_scope" ] } }, "required": [ "message", "code" ] } } } }, "429": { "description": "Too many requests for this key. Wait for the `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Too Many Attempts." ] }, "code": { "type": "string", "examples": [ "rate_limited" ] } }, "required": [ "message", "code" ] } } } } } } }, "\/bookings\/{booking}": { "get": { "operationId": "getBooking", "summary": "Get a booking", "tags": [ "Bookings" ], "parameters": [ { "name": "booking", "in": "path", "required": true, "description": "The booking id.", "schema": { "type": "integer" }, "example": 64 } ], "responses": { "200": { "description": "`BookingResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/BookingResource" } }, "required": [ "data" ] } } } }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Missing, invalid, expired or revoked API key. Send it as \"Authorization: Bearer vk_live_...\" (or vk_test_... for test mode)." ] }, "code": { "type": "string", "examples": [ "unauthenticated" ] } }, "required": [ "message", "code" ] } } } }, "403": { "description": "The key does not have the `bookings:read` scope.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "This API key does not have the bookings:read scope." ] }, "code": { "type": "string", "examples": [ "missing_scope" ] } }, "required": [ "message", "code" ] } } } }, "404": { "description": "No record with that id belongs to your account.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "That record was not found." ] }, "code": { "type": "string", "examples": [ "not_found" ] } }, "required": [ "message", "code" ] } } } }, "429": { "description": "Too many requests for this key. Wait for the `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Too Many Attempts." ] }, "code": { "type": "string", "examples": [ "rate_limited" ] } }, "required": [ "message", "code" ] } } } } } } }, "\/outbound-calls": { "get": { "operationId": "listOutboundCalls", "description": "Your outbound AI calls, newest first: the ones you queued and those from speed-to-lead,\ncampaigns and agents.", "summary": "List outbound calls", "tags": [ "Outbound calls" ], "parameters": [ { "name": "status", "in": "query", "schema": { "$ref": "#\/components\/schemas\/OutboundCallStatus" } }, { "name": "source", "in": "query", "description": "What started the call: `api`, `speed_to_lead`, `campaign` or `agent_dial`.\n| |\n|---|\n| `speed_to_lead` The AI calls back someone who just asked to be contacted. |\n| `agent_dial` A GH Live agent dials a number by hand from the workspace. |\n| `campaign` The AI works through a client's campaign contact list. |\n| `api` The client's own system queued an AI call through the public API or platform MCP server. |", "schema": { "$ref": "#\/components\/schemas\/OutboundSource" } }, { "name": "phone_number", "in": "query", "description": "Calls to this number, in any common US format.", "schema": { "type": "string", "maxLength": 32 } }, { "name": "since", "in": "query", "description": "Calls queued at or after this time (ISO 8601).", "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "description": "Calls queued before this time (ISO 8601).", "schema": { "type": "string", "format": "date-time" } }, { "name": "per_page", "in": "query", "description": "How many items per page, 1 to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "description": "The `meta.next_cursor` (or `meta.prev_cursor`) of the previous page.", "schema": { "type": [ "string", "null" ], "maxLength": 1024 } } ], "responses": { "200": { "description": "Paginated set of `OutboundCallResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/OutboundCallResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "next_cursor": { "type": [ "string", "null" ], "description": "The \"cursor\" that points to the next set of items." }, "prev_cursor": { "type": [ "string", "null" ], "description": "The \"cursor\" that points to the previous set of items." } }, "required": [ "path", "per_page", "next_cursor", "prev_cursor" ] } }, "required": [ "data", "links", "meta" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Missing, invalid, expired or revoked API key. Send it as \"Authorization: Bearer vk_live_...\" (or vk_test_... for test mode)." ] }, "code": { "type": "string", "examples": [ "unauthenticated" ] } }, "required": [ "message", "code" ] } } } }, "403": { "description": "The key does not have the `outbound:write` scope.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "This API key does not have the outbound:write scope." ] }, "code": { "type": "string", "examples": [ "missing_scope" ] } }, "required": [ "message", "code" ] } } } }, "429": { "description": "Too many requests for this key. Wait for the `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Too Many Attempts." ] }, "code": { "type": "string", "examples": [ "rate_limited" ] } }, "required": [ "message", "code" ] } } } } } }, "post": { "operationId": "createOutboundCall", "description": "Queue an AI call. Every call is checked against the same rules as calls from the portal:\nthe number must have AI-call consent on record (marketing consent for `marketing` calls) and\nmust not be on your or GH's Do Not Call list. Those refusals return 422 with the `decision`.\n\nA call that cannot ring right now (outside 8am to 8pm where the number is, three calls in the\nlast 24 hours, or already on a call) is still accepted: `decision.retry_at` says when it will\nring. Asking again for a number that is still waiting returns the same call.\n\nWith a test key (`vk_test_`) the call is checked exactly the same way (against your test Do Not\nCall list and test consents), except the free trial's AI minutes, and is then simulated: it never\nrings anyone, moves from `queued` to `in_progress` to `completed` with a sample transcript within\na few seconds, and sends `outbound_call.completed` to your test webhook endpoints.", "summary": "Queue an outbound AI call", "tags": [ "Outbound calls" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/StoreOutboundCallRequest" } } } }, "responses": { "202": { "description": "Accepted. `decision.allowed` is true when the call can ring now; otherwise `decision.retry_at` says when it will.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "data": { "id": 88, "source": "api", "purpose": "marketing", "status": "queued", "phone_number": "+15125550123" }, "decision": { "allowed": false, "reason": "outside_hours", "message": "It is outside calling hours (8am to 8pm) where that number is.", "retry_at": "2026-09-29T08:00:00-05:00" } } ], "properties": { "data": { "$ref": "#\/components\/schemas\/OutboundCallResource" }, "decision": { "type": "object", "properties": { "allowed": { "type": "boolean" }, "reason": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "retry_at": { "type": [ "string", "null" ] } }, "required": [ "allowed", "reason", "message", "retry_at" ] } }, "required": [ "data", "decision" ] } } } }, "422": { "description": "The call can never be placed: `do_not_call`, `no_consent`, `invalid_number`, `outbound_disabled`, `service_inactive`, `terms_not_accepted`, `hipaa_marketing`, `trial_minutes_exhausted` (the free trial's included AI minutes are used up) or `no_receptionist`.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "message": "That number is on a Do Not Call list.", "code": "do_not_call", "decision": { "allowed": false, "reason": "do_not_call", "message": "That number is on a Do Not Call list.", "retry_at": null } } ], "properties": { "message": { "type": "string" }, "code": { "type": "string" }, "decision": { "type": "object", "properties": { "allowed": { "type": "boolean" }, "reason": { "type": "string" }, "message": { "type": "string" }, "retry_at": { "type": [ "string", "null" ] } }, "required": [ "allowed", "reason", "message", "retry_at" ] } }, "required": [ "message", "code" ] } } } }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Missing, invalid, expired or revoked API key. Send it as \"Authorization: Bearer vk_live_...\" (or vk_test_... for test mode)." ] }, "code": { "type": "string", "examples": [ "unauthenticated" ] } }, "required": [ "message", "code" ] } } } }, "403": { "description": "The key does not have the `outbound:write` scope.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "This API key does not have the outbound:write scope." ] }, "code": { "type": "string", "examples": [ "missing_scope" ] } }, "required": [ "message", "code" ] } } } }, "429": { "description": "Too many requests for this key. Wait for the `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Too Many Attempts." ] }, "code": { "type": "string", "examples": [ "rate_limited" ] } }, "required": [ "message", "code" ] } } } } } } }, "\/outbound-calls\/{outboundCall}": { "get": { "operationId": "getOutboundCall", "description": "Check on a call you queued: its status, why it was blocked or delayed and, once it ended, its\ntranscript (not for HIPAA-mode accounts).", "summary": "Get an outbound call", "tags": [ "Outbound calls" ], "parameters": [ { "name": "outboundCall", "in": "path", "required": true, "description": "The outbound call id.", "schema": { "type": "integer" }, "example": 88 } ], "responses": { "200": { "description": "`OutboundCallResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/OutboundCallResource" } }, "required": [ "data" ] } } } }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Missing, invalid, expired or revoked API key. Send it as \"Authorization: Bearer vk_live_...\" (or vk_test_... for test mode)." ] }, "code": { "type": "string", "examples": [ "unauthenticated" ] } }, "required": [ "message", "code" ] } } } }, "403": { "description": "The key does not have the `outbound:write` scope.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "This API key does not have the outbound:write scope." ] }, "code": { "type": "string", "examples": [ "missing_scope" ] } }, "required": [ "message", "code" ] } } } }, "404": { "description": "No record with that id belongs to your account.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "That record was not found." ] }, "code": { "type": "string", "examples": [ "not_found" ] } }, "required": [ "message", "code" ] } } } }, "429": { "description": "Too many requests for this key. Wait for the `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Too Many Attempts." ] }, "code": { "type": "string", "examples": [ "rate_limited" ] } }, "required": [ "message", "code" ] } } } } } } }, "\/do-not-call": { "get": { "operationId": "listDoNotCallEntries", "description": "Your Do Not Call list, newest first. Pass `phone_number` to look up one number.", "summary": "List Do Not Call entries", "tags": [ "Do Not Call" ], "parameters": [ { "name": "phone_number", "in": "query", "description": "Look up one number, in any common US format.", "schema": { "type": "string", "maxLength": 32 } }, { "name": "source", "in": "query", "schema": { "type": "string", "enum": [ "opt_out", "manual" ] } }, { "name": "per_page", "in": "query", "description": "How many items per page, 1 to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "description": "The `meta.next_cursor` (or `meta.prev_cursor`) of the previous page.", "schema": { "type": [ "string", "null" ], "maxLength": 1024 } } ], "responses": { "200": { "description": "Paginated set of `DoNotCallEntryResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/DoNotCallEntryResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "next_cursor": { "type": [ "string", "null" ], "description": "The \"cursor\" that points to the next set of items." }, "prev_cursor": { "type": [ "string", "null" ], "description": "The \"cursor\" that points to the previous set of items." } }, "required": [ "path", "per_page", "next_cursor", "prev_cursor" ] } }, "required": [ "data", "links", "meta" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Missing, invalid, expired or revoked API key. Send it as \"Authorization: Bearer vk_live_...\" (or vk_test_... for test mode)." ] }, "code": { "type": "string", "examples": [ "unauthenticated" ] } }, "required": [ "message", "code" ] } } } }, "403": { "description": "The key does not have the `dnc:read` scope.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "This API key does not have the dnc:read scope." ] }, "code": { "type": "string", "examples": [ "missing_scope" ] } }, "required": [ "message", "code" ] } } } }, "429": { "description": "Too many requests for this key. Wait for the `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Too Many Attempts." ] }, "code": { "type": "string", "examples": [ "rate_limited" ] } }, "required": [ "message", "code" ] } } } } } }, "post": { "operationId": "createDoNotCallEntry", "description": "Add a number. Send `opted_out: true` when the person asked not to be called: it becomes a\npermanent opt-out and their AI-call consent is revoked. Adding a number already on the list\nreturns the existing entry with status 200.", "summary": "Add a number to the Do Not Call list", "tags": [ "Do Not Call" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/StoreDoNotCallEntryRequest" } } } }, "responses": { "200": { "description": "The number was already on the list: the existing entry.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/DoNotCallEntryResource" } }, "required": [ "data" ] } } } }, "422": { "description": "Validation failed, or the number is not a valid US number (`invalid_number`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message" ] } } } }, "201": { "description": "The entry.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/DoNotCallEntryResource" } }, "required": [ "data" ] } } } }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Missing, invalid, expired or revoked API key. Send it as \"Authorization: Bearer vk_live_...\" (or vk_test_... for test mode)." ] }, "code": { "type": "string", "examples": [ "unauthenticated" ] } }, "required": [ "message", "code" ] } } } }, "403": { "description": "The key does not have the `dnc:write` scope.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "This API key does not have the dnc:write scope." ] }, "code": { "type": "string", "examples": [ "missing_scope" ] } }, "required": [ "message", "code" ] } } } }, "429": { "description": "Too many requests for this key. Wait for the `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Too Many Attempts." ] }, "code": { "type": "string", "examples": [ "rate_limited" ] } }, "required": [ "message", "code" ] } } } } } } }, "\/do-not-call\/{entry}": { "delete": { "operationId": "deleteDoNotCallEntry", "description": "Remove a number you added. People who asked not to be called can never be removed.", "summary": "Remove a number from the Do Not Call list", "tags": [ "Do Not Call" ], "parameters": [ { "name": "entry", "in": "path", "required": true, "description": "The entry id.", "schema": { "type": "integer" }, "example": 57 } ], "responses": { "204": { "description": "Removed." }, "403": { "description": "The entry is an opt-out and cannot be removed (`opt_out_permanent`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "message", "code" ] } } } }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Missing, invalid, expired or revoked API key. Send it as \"Authorization: Bearer vk_live_...\" (or vk_test_... for test mode)." ] }, "code": { "type": "string", "examples": [ "unauthenticated" ] } }, "required": [ "message", "code" ] } } } }, "404": { "description": "No record with that id belongs to your account.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "That record was not found." ] }, "code": { "type": "string", "examples": [ "not_found" ] } }, "required": [ "message", "code" ] } } } }, "429": { "description": "Too many requests for this key. Wait for the `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Too Many Attempts." ] }, "code": { "type": "string", "examples": [ "rate_limited" ] } }, "required": [ "message", "code" ] } } } } } } }, "\/blocked-callers": { "get": { "operationId": "listBlockedCallers", "description": "Your blocked callers, newest first. Pass `pattern` to look up one number or prefix.", "summary": "List blocked callers", "tags": [ "Blocked callers" ], "parameters": [ { "name": "pattern", "in": "query", "description": "Look up one number (any common US format) or prefix (digits ending in `*`).", "schema": { "type": "string", "maxLength": 32 } }, { "name": "source", "in": "query", "description": "`manual` (you added it), `ai` (the receptionist blocked a spam caller) or `call` (blocked from a call's page).\n| |\n|---|\n| `manual` Typed in on the blocked callers page or sent through the API. |\n| `ai` The AI receptionist judged a call spam and blocked the number. |\n| `call` Blocked from a call's page. |", "schema": { "$ref": "#\/components\/schemas\/BlockedCallerSource" } }, { "name": "per_page", "in": "query", "description": "How many items per page, 1 to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "description": "The `meta.next_cursor` (or `meta.prev_cursor`) of the previous page.", "schema": { "type": [ "string", "null" ], "maxLength": 1024 } } ], "responses": { "200": { "description": "Paginated set of `BlockedCallerResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/BlockedCallerResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "next_cursor": { "type": [ "string", "null" ], "description": "The \"cursor\" that points to the next set of items." }, "prev_cursor": { "type": [ "string", "null" ], "description": "The \"cursor\" that points to the previous set of items." } }, "required": [ "path", "per_page", "next_cursor", "prev_cursor" ] } }, "required": [ "data", "links", "meta" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Missing, invalid, expired or revoked API key. Send it as \"Authorization: Bearer vk_live_...\" (or vk_test_... for test mode)." ] }, "code": { "type": "string", "examples": [ "unauthenticated" ] } }, "required": [ "message", "code" ] } } } }, "403": { "description": "The key does not have the `dnc:read` scope.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "This API key does not have the dnc:read scope." ] }, "code": { "type": "string", "examples": [ "missing_scope" ] } }, "required": [ "message", "code" ] } } } }, "429": { "description": "Too many requests for this key. Wait for the `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Too Many Attempts." ] }, "code": { "type": "string", "examples": [ "rate_limited" ] } }, "required": [ "message", "code" ] } } } } } }, "post": { "operationId": "createBlockedCaller", "description": "Block a number, or every number starting with a prefix (`512555*`). Adding a pattern already on the list\nreturns the existing entry with status 200.", "summary": "Block a caller", "tags": [ "Blocked callers" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/StoreBlockedCallerRequest" } } } }, "responses": { "200": { "description": "The pattern was already on the list: the existing entry.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/BlockedCallerResource" } }, "required": [ "data" ] } } } }, "422": { "description": "Validation failed, or the pattern is neither a US number nor a prefix (`invalid_pattern`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message" ] } } } }, "201": { "description": "The entry.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/BlockedCallerResource" } }, "required": [ "data" ] } } } }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Missing, invalid, expired or revoked API key. Send it as \"Authorization: Bearer vk_live_...\" (or vk_test_... for test mode)." ] }, "code": { "type": "string", "examples": [ "unauthenticated" ] } }, "required": [ "message", "code" ] } } } }, "403": { "description": "The key does not have the `dnc:write` scope.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "This API key does not have the dnc:write scope." ] }, "code": { "type": "string", "examples": [ "missing_scope" ] } }, "required": [ "message", "code" ] } } } }, "429": { "description": "Too many requests for this key. Wait for the `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Too Many Attempts." ] }, "code": { "type": "string", "examples": [ "rate_limited" ] } }, "required": [ "message", "code" ] } } } } } } }, "\/blocked-callers\/{entry}": { "delete": { "operationId": "deleteBlockedCaller", "summary": "Unblock a caller", "tags": [ "Blocked callers" ], "parameters": [ { "name": "entry", "in": "path", "required": true, "description": "The entry id.", "schema": { "type": "integer" }, "example": 31 } ], "responses": { "204": { "description": "Removed." }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Missing, invalid, expired or revoked API key. Send it as \"Authorization: Bearer vk_live_...\" (or vk_test_... for test mode)." ] }, "code": { "type": "string", "examples": [ "unauthenticated" ] } }, "required": [ "message", "code" ] } } } }, "403": { "description": "The key does not have the `dnc:write` scope.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "This API key does not have the dnc:write scope." ] }, "code": { "type": "string", "examples": [ "missing_scope" ] } }, "required": [ "message", "code" ] } } } }, "404": { "description": "No record with that id belongs to your account.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "That record was not found." ] }, "code": { "type": "string", "examples": [ "not_found" ] } }, "required": [ "message", "code" ] } } } }, "429": { "description": "Too many requests for this key. Wait for the `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Too Many Attempts." ] }, "code": { "type": "string", "examples": [ "rate_limited" ] } }, "required": [ "message", "code" ] } } } } } } }, "\/chats": { "get": { "operationId": "listChats", "description": "Your website chats, newest first.", "summary": "List chats", "tags": [ "Chats" ], "parameters": [ { "name": "status", "in": "query", "schema": { "$ref": "#\/components\/schemas\/ChatConversationStatus" } }, { "name": "since", "in": "query", "description": "Chats started at or after this time (ISO 8601).", "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "description": "Chats started before this time (ISO 8601).", "schema": { "type": "string", "format": "date-time" } }, { "name": "per_page", "in": "query", "description": "How many items per page, 1 to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "description": "The `meta.next_cursor` (or `meta.prev_cursor`) of the previous page.", "schema": { "type": [ "string", "null" ], "maxLength": 1024 } } ], "responses": { "200": { "description": "Paginated set of `ChatResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/ChatResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "next_cursor": { "type": [ "string", "null" ], "description": "The \"cursor\" that points to the next set of items." }, "prev_cursor": { "type": [ "string", "null" ], "description": "The \"cursor\" that points to the previous set of items." } }, "required": [ "path", "per_page", "next_cursor", "prev_cursor" ] } }, "required": [ "data", "links", "meta" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Missing, invalid, expired or revoked API key. Send it as \"Authorization: Bearer vk_live_...\" (or vk_test_... for test mode)." ] }, "code": { "type": "string", "examples": [ "unauthenticated" ] } }, "required": [ "message", "code" ] } } } }, "403": { "description": "The key does not have the `chats:read` scope.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "This API key does not have the chats:read scope." ] }, "code": { "type": "string", "examples": [ "missing_scope" ] } }, "required": [ "message", "code" ] } } } }, "429": { "description": "Too many requests for this key. Wait for the `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Too Many Attempts." ] }, "code": { "type": "string", "examples": [ "rate_limited" ] } }, "required": [ "message", "code" ] } } } } } } }, "\/chats\/{chat}": { "get": { "operationId": "getChat", "description": "One chat with its messages. HIPAA-mode accounts get the chat without messages or handoff summary.", "summary": "Get a chat", "tags": [ "Chats" ], "parameters": [ { "name": "chat", "in": "path", "required": true, "description": "The chat id.", "schema": { "type": "integer" }, "example": 205 } ], "responses": { "200": { "description": "`ChatResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/ChatResource" } }, "required": [ "data" ] } } } }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Missing, invalid, expired or revoked API key. Send it as \"Authorization: Bearer vk_live_...\" (or vk_test_... for test mode)." ] }, "code": { "type": "string", "examples": [ "unauthenticated" ] } }, "required": [ "message", "code" ] } } } }, "403": { "description": "The key does not have the `chats:read` scope.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "This API key does not have the chats:read scope." ] }, "code": { "type": "string", "examples": [ "missing_scope" ] } }, "required": [ "message", "code" ] } } } }, "404": { "description": "No record with that id belongs to your account.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "That record was not found." ] }, "code": { "type": "string", "examples": [ "not_found" ] } }, "required": [ "message", "code" ] } } } }, "429": { "description": "Too many requests for this key. Wait for the `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Too Many Attempts." ] }, "code": { "type": "string", "examples": [ "rate_limited" ] } }, "required": [ "message", "code" ] } } } } } } }, "\/chats\/{chat}\/messages": { "post": { "operationId": "createChatMessage", "description": "Reply in a live chat as your team. The visitor sees it at once, from \"Team\". A reply to a chat the AI\nis answering takes it over. Limited to 30 replies a minute per key, on top of the overall limit.\n\n```bash\ncurl -X POST https:\/\/vocenya.com\/api\/public\/v1\/chats\/205\/messages \\\n -H \"Authorization: Bearer $VOCENYA_API_KEY\" \\\n -H \"Content-Type: application\/json\" \\\n -d '{\"body\": \"Thanks for waiting! We have an opening on Thursday at 3pm.\"}'\n```", "summary": "Reply in a chat", "tags": [ "Chats" ], "parameters": [ { "name": "chat", "in": "path", "required": true, "description": "The chat id.", "schema": { "type": "integer" }, "example": 205 } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/StoreChatMessageRequest" } } } }, "responses": { "201": { "description": "The message that was sent.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/ChatMessageResource" } }, "required": [ "data" ] } } } }, "422": { "description": "A WhatsApp chat whose 24-hour reply window has closed (`whatsapp_window_closed`): follow up with an approved template from the inbox.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string" }, "hint": { "type": "string" } }, "required": [ "message", "code", "hint" ] } } } }, "403": { "description": "Website live chat is not part of the plan (`live_chat_unavailable`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "message", "code" ] } } } }, "409": { "description": "The chat has ended (`chat_closed`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "message", "code" ] } } } }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Missing, invalid, expired or revoked API key. Send it as \"Authorization: Bearer vk_live_...\" (or vk_test_... for test mode)." ] }, "code": { "type": "string", "examples": [ "unauthenticated" ] } }, "required": [ "message", "code" ] } } } }, "404": { "description": "No record with that id belongs to your account.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "That record was not found." ] }, "code": { "type": "string", "examples": [ "not_found" ] } }, "required": [ "message", "code" ] } } } }, "429": { "description": "Too many requests for this key. Wait for the `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Too Many Attempts." ] }, "code": { "type": "string", "examples": [ "rate_limited" ] } }, "required": [ "message", "code" ] } } } } } } }, "\/chats\/{chat}\/close": { "post": { "operationId": "closeChat", "description": "End a chat. The visitor sees that it ended. Closing a chat that already ended changes nothing.\n\n```bash\ncurl -X POST https:\/\/vocenya.com\/api\/public\/v1\/chats\/205\/close \\\n -H \"Authorization: Bearer $VOCENYA_API_KEY\"\n```", "summary": "Close a chat", "tags": [ "Chats" ], "parameters": [ { "name": "chat", "in": "path", "required": true, "description": "The chat id.", "schema": { "type": "integer" }, "example": 205 } ], "responses": { "200": { "description": "`ChatResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/ChatResource" } }, "required": [ "data" ] } } } }, "403": { "description": "Website live chat is not part of the plan (`live_chat_unavailable`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "message", "code" ] } } } }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Missing, invalid, expired or revoked API key. Send it as \"Authorization: Bearer vk_live_...\" (or vk_test_... for test mode)." ] }, "code": { "type": "string", "examples": [ "unauthenticated" ] } }, "required": [ "message", "code" ] } } } }, "404": { "description": "No record with that id belongs to your account.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "That record was not found." ] }, "code": { "type": "string", "examples": [ "not_found" ] } }, "required": [ "message", "code" ] } } } }, "429": { "description": "Too many requests for this key. Wait for the `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Too Many Attempts." ] }, "code": { "type": "string", "examples": [ "rate_limited" ] } }, "required": [ "message", "code" ] } } } } } } }, "\/webhook-endpoints": { "get": { "operationId": "listWebhookEndpoints", "summary": "List webhook endpoints", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Array of `WebhookEndpointResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/WebhookEndpointResource" } } }, "required": [ "data" ] } } } }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Missing, invalid, expired or revoked API key. Send it as \"Authorization: Bearer vk_live_...\" (or vk_test_... for test mode)." ] }, "code": { "type": "string", "examples": [ "unauthenticated" ] } }, "required": [ "message", "code" ] } } } }, "403": { "description": "The key does not have the `webhooks:manage` scope.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "This API key does not have the webhooks:manage scope." ] }, "code": { "type": "string", "examples": [ "missing_scope" ] } }, "required": [ "message", "code" ] } } } }, "429": { "description": "Too many requests for this key. Wait for the `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Too Many Attempts." ] }, "code": { "type": "string", "examples": [ "rate_limited" ] } }, "required": [ "message", "code" ] } } } } } }, "post": { "operationId": "createWebhookEndpoint", "description": "Add an endpoint. The response includes its signing `secret`: store it now, it is not shown again.", "summary": "Create a webhook endpoint", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/StoreWebhookEndpointRequest" } } } }, "responses": { "201": { "description": "The endpoint and its signing secret.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "data": { "id": 3, "url": "https:\/\/hooks.example.com\/vocenya", "description": "Our CRM", "events": [ "lead.created" ], "enabled": true, "created_at": "2026-09-27T15:04:05+00:00" }, "secret": "whsec_4hW0cB1m9GqS7pXvL2eYt8Kz3nRd6FjA5uVo0iQs" } ], "properties": { "data": { "$ref": "#\/components\/schemas\/WebhookEndpointResource" }, "secret": { "type": "string" } }, "required": [ "data", "secret" ] } } } }, "422": { "description": "Validation failed, the URL is not a public HTTPS address (`unsafe_url`), or the account already has 10 endpoints (`too_many_endpoints`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message" ] } } } }, "403": { "description": "The key lacks the read scope of a subscribed event, for example `leads:read` for `lead.created` (`missing_scope`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "message", "code" ] } } } }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Missing, invalid, expired or revoked API key. Send it as \"Authorization: Bearer vk_live_...\" (or vk_test_... for test mode)." ] }, "code": { "type": "string", "examples": [ "unauthenticated" ] } }, "required": [ "message", "code" ] } } } }, "429": { "description": "Too many requests for this key. Wait for the `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Too Many Attempts." ] }, "code": { "type": "string", "examples": [ "rate_limited" ] } }, "required": [ "message", "code" ] } } } } } } }, "\/webhook-endpoints\/{webhookEndpoint}": { "delete": { "operationId": "deleteWebhookEndpoint", "description": "Delete an endpoint. Queued deliveries to it are dropped.", "summary": "Delete a webhook endpoint", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhookEndpoint", "in": "path", "required": true, "description": "The endpoint id.", "schema": { "type": "integer" }, "example": 3 } ], "responses": { "204": { "description": "Deleted." }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Missing, invalid, expired or revoked API key. Send it as \"Authorization: Bearer vk_live_...\" (or vk_test_... for test mode)." ] }, "code": { "type": "string", "examples": [ "unauthenticated" ] } }, "required": [ "message", "code" ] } } } }, "403": { "description": "The key does not have the `webhooks:manage` scope.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "This API key does not have the webhooks:manage scope." ] }, "code": { "type": "string", "examples": [ "missing_scope" ] } }, "required": [ "message", "code" ] } } } }, "404": { "description": "No record with that id belongs to your account.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "That record was not found." ] }, "code": { "type": "string", "examples": [ "not_found" ] } }, "required": [ "message", "code" ] } } } }, "429": { "description": "Too many requests for this key. Wait for the `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Too Many Attempts." ] }, "code": { "type": "string", "examples": [ "rate_limited" ] } }, "required": [ "message", "code" ] } } } } } } }, "\/webhook-endpoints\/{webhookEndpoint}\/test": { "post": { "operationId": "testWebhookEndpoint", "description": "Send a signed `webhook.test` event to this endpoint, with `{\"message\": \"...\"}` as its data. Pass\n`event` to get a sample of a real event instead (for example `chat.message.created`), with made-up\ndata and `\"sample\": true`, cut down to ids for HIPAA-mode accounts like the real thing. It is\ndelivered in the background like any other event, even when the endpoint is paused.\n\n```bash\ncurl -X POST https:\/\/vocenya.com\/api\/public\/v1\/webhook-endpoints\/3\/test \\\n -H \"Authorization: Bearer $VOCENYA_API_KEY\" \\\n -H \"Content-Type: application\/json\" \\\n -d '{\"event\": \"chat.message.created\"}'\n```", "summary": "Send a test event", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhookEndpoint", "in": "path", "required": true, "description": "The endpoint id.", "schema": { "type": "integer" }, "example": 3 } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/TestWebhookEndpointRequest" } } } }, "responses": { "202": { "description": "The queued delivery.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/WebhookDeliveryResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "The API key is missing, invalid, expired or revoked.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Missing, invalid, expired or revoked API key. Send it as \"Authorization: Bearer vk_live_...\" (or vk_test_... for test mode)." ] }, "code": { "type": "string", "examples": [ "unauthenticated" ] } }, "required": [ "message", "code" ] } } } }, "403": { "description": "The key does not have the `webhooks:manage` scope.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "This API key does not have the webhooks:manage scope." ] }, "code": { "type": "string", "examples": [ "missing_scope" ] } }, "required": [ "message", "code" ] } } } }, "404": { "description": "No record with that id belongs to your account.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "That record was not found." ] }, "code": { "type": "string", "examples": [ "not_found" ] } }, "required": [ "message", "code" ] } } } }, "429": { "description": "Too many requests for this key. Wait for the `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": [ "Too Many Attempts." ] }, "code": { "type": "string", "examples": [ "rate_limited" ] } }, "required": [ "message", "code" ] } } } } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "description": "An organization API key from the Developers page of the Vocenya portal, sent as `Authorization: Bearer vk_live_...`. Test keys (`vk_test_...`) work the same way on your test data only.", "scheme": "bearer", "bearerFormat": "vk_live_..." } }, "schemas": { "AnsweredBy": { "type": "string", "description": "Who the carrier's answering machine detection heard pick up an outbound AI call. Null when detection gave no result.\n", "enum": [ "human", "machine", "unknown" ], "title": "AnsweredBy" }, "BlockedCallerResource": { "type": "object", "properties": { "id": { "type": "integer" }, "livemode": { "type": "boolean", "description": "`true` for live data, `false` for test data (created with a `vk_test_` key)." }, "pattern": { "type": "string", "description": "An E.164 number, or a prefix ending in `*` that blocks every number starting with it.", "examples": [ "+15125550123" ] }, "source": { "description": "`manual` when you added it, `ai` when the receptionist blocked a spam caller, `call` when blocked from a call's page.\n| |\n|---|\n| `manual` Typed in on the blocked callers page or sent through the API. |\n| `ai` The AI receptionist judged a call spam and blocked the number. |\n| `call` Blocked from a call's page. |", "$ref": "#\/components\/schemas\/BlockedCallerSource" }, "note": { "type": [ "string", "null" ] }, "calls_blocked": { "type": "integer", "description": "How many calls this entry has turned away." }, "last_blocked_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "livemode", "pattern", "source", "note", "calls_blocked", "last_blocked_at", "created_at" ], "title": "BlockedCallerResource" }, "BlockedCallerSource": { "type": "string", "description": "How a number ended up on a client's blocked callers list.\n| |\n|---|\n| `manual` Typed in on the blocked callers page or sent through the API. |\n| `ai` The AI receptionist judged a call spam and blocked the number. |\n| `call` Blocked from a call's page. |", "enum": [ "manual", "ai", "call" ], "title": "BlockedCallerSource" }, "BookingResource": { "type": "object", "properties": { "id": { "type": "integer" }, "livemode": { "type": "boolean", "description": "`true` for live data, `false` for test data (created with a `vk_test_` key)." }, "provider": { "description": "The calendar or software the appointment was booked into.", "$ref": "#\/components\/schemas\/IntegrationProvider" }, "external_reference": { "type": [ "string", "null" ], "description": "The appointment's id in that calendar or software." }, "starts_at": { "type": "string" }, "duration_minutes": { "type": "integer" }, "name": { "type": [ "string", "null" ], "examples": [ "Maria Rivera" ] }, "phone_number": { "type": [ "string", "null" ], "examples": [ "+15125550123" ] }, "call_id": { "type": [ "integer", "null" ] }, "outbound_call_id": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "livemode", "provider", "external_reference", "starts_at", "duration_minutes", "name", "phone_number", "call_id", "outbound_call_id", "created_at" ], "title": "BookingResource" }, "CallDirection": { "type": "string", "enum": [ "inbound", "outbound" ], "title": "CallDirection" }, "CallPurpose": { "type": "string", "description": "Why an outbound call is made. Telemarketing needs prior express written consent for AI voices.\n", "enum": [ "marketing", "informational" ], "title": "CallPurpose" }, "CallResource": { "type": "object", "properties": { "id": { "type": "integer" }, "livemode": { "type": "boolean", "description": "`true` for live data, `false` for test data (created with a `vk_test_` key)." }, "direction": { "description": "Whether the call came in to, or went out from, your number.", "$ref": "#\/components\/schemas\/CallDirection" }, "status": { "$ref": "#\/components\/schemas\/CallStatus" }, "from_number": { "type": "string", "examples": [ "+15125550123" ] }, "caller_name": { "type": [ "string", "null" ], "description": "The caller's name as the carrier reported it (CNAM), when known." }, "to_number": { "type": "string", "examples": [ "+15125550100" ] }, "spam": { "type": "boolean", "description": "Whether the call was judged spam: by the receptionist, or because the number is on your blocked callers list (`status` is then `blocked`)." }, "routed_to": { "anyOf": [ { "description": "Where the call was routed: the AI receptionist, a GH Live agent, your phone or voicemail.", "$ref": "#\/components\/schemas\/RoutingAction" }, { "type": "null" } ] }, "started_at": { "type": "string" }, "answered_at": { "type": [ "string", "null" ] }, "ended_at": { "type": [ "string", "null" ] }, "duration_seconds": { "type": [ "integer", "null" ] }, "disposition": { "type": [ "string", "null" ] }, "summary": { "type": [ "string", "null" ], "description": "The AI's summary of the call. Not included for HIPAA-mode accounts." }, "handoff_summary": { "type": [ "string", "null" ], "description": "What the AI told the person it handed the call to. Not included for HIPAA-mode accounts." }, "transcript": { "type": [ "array", "null" ], "description": "The conversation, turn by turn. Only on `GET \/calls\/{id}`, and never for HIPAA-mode accounts.", "items": { "type": "object", "properties": { "role": { "type": "string" }, "text": { "type": "string" } }, "required": [ "role", "text" ] } }, "lead_ids": { "type": "array", "description": "Leads the AI captured on this call. Only on `GET \/calls\/{id}`.", "items": {} }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "livemode", "direction", "status", "from_number", "caller_name", "to_number", "spam", "routed_to", "started_at", "answered_at", "ended_at", "duration_seconds", "disposition", "created_at" ], "title": "CallResource" }, "CallStatus": { "type": "string", "description": "| |\n|---|\n| `ringing` |\n| `in_progress` |\n| `completed` |\n| `missed` |\n| `failed` |\n| `blocked` The caller's number is on the client's blocked callers list: turned away before anyone answered. |", "enum": [ "ringing", "in_progress", "completed", "missed", "failed", "blocked" ], "title": "CallStatus" }, "ChatConversationStatus": { "type": "string", "description": "Who is answering a website chat right now.\n", "enum": [ "ai", "with_agent", "with_owner", "closed" ], "title": "ChatConversationStatus" }, "ChatMessageResource": { "type": "object", "properties": { "id": { "type": "integer" }, "livemode": { "type": "boolean", "description": "`true` for live data, `false` for test data (created with a `vk_test_` key)." }, "chat_id": { "type": "integer", "examples": [ 205 ] }, "sender": { "type": "string", "description": "Who wrote it: `visitor`, `ai`, `agent` (a GH Live agent), `owner` (the client's team or the API) or `system`." }, "role": { "type": "string", "description": "What the widget shows: `visitor`, `ai`, `team` or `system`.", "enum": [ "visitor", "ai", "team", "system" ], "examples": [ "team" ] }, "author": { "type": "string", "examples": [ "Team" ] }, "body": { "type": "string", "description": "The text. Not included for HIPAA-mode accounts." }, "via_api": { "type": "boolean", "description": "Whether it was sent with the public API." }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "livemode", "chat_id", "sender", "role", "author", "via_api", "created_at" ], "title": "ChatMessageResource" }, "ChatResource": { "type": "object", "properties": { "id": { "type": "integer" }, "livemode": { "type": "boolean", "description": "`true` for live data, `false` for test data (created with a `vk_test_` key)." }, "channel": { "type": "string", "description": "Where the chat happens: `web` (the website widget) or `whatsapp`.", "examples": [ "web" ] }, "contact_address": { "type": [ "string", "null" ], "description": "The customer's WhatsApp number in E.164 on `whatsapp` chats; `null` on website chats." }, "reply_window_open": { "type": [ "boolean", "null" ], "description": "On `whatsapp` chats, whether WhatsApp's 24-hour window for free-form replies is open now." }, "status": { "description": "`ai` while the AI answers, `with_agent` or `with_owner` after a handoff, then `closed`.", "$ref": "#\/components\/schemas\/ChatConversationStatus" }, "page_url": { "type": [ "string", "null" ], "examples": [ "https:\/\/www.example.com\/contact" ] }, "handoff_summary": { "type": [ "string", "null" ], "description": "What the AI passed on when it handed the chat to a person. Not included for HIPAA-mode accounts." }, "handed_off_at": { "type": [ "string", "null" ] }, "closed_at": { "type": [ "string", "null" ] }, "last_message_at": { "type": [ "string", "null" ] }, "lead_id": { "type": [ "integer", "null" ], "description": "The lead the AI captured in this chat, if any." }, "messages": { "type": "array", "description": "The conversation. Only on `GET \/chats\/{id}`, and never for HIPAA-mode accounts.", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "livemode": { "type": "boolean" }, "sender": { "type": "string" }, "role": { "type": "string", "enum": [ "visitor", "ai", "team", "system" ] }, "author": { "type": "string" }, "body": { "type": "string" }, "via_api": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "livemode", "sender", "role", "author", "body", "via_api", "created_at" ] } }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "livemode", "channel", "contact_address", "reply_window_open", "status", "page_url", "handed_off_at", "closed_at", "last_message_at", "lead_id", "created_at" ], "title": "ChatResource" }, "DoNotCallEntryResource": { "type": "object", "properties": { "id": { "type": "integer" }, "livemode": { "type": "boolean", "description": "`true` for live data, `false` for test data (created with a `vk_test_` key)." }, "phone_number": { "type": "string", "examples": [ "+15125550123" ] }, "source": { "description": "`opt_out` when the person asked not to be called (permanent), `manual` when you added it.\n| |\n|---|\n| `opt_out` The person asked not to be called: on an AI call, to a GH Live agent, or to the client. |\n| `manual` Added by GH staff or the client. |\n| `national_registry` Imported from the FTC National Do Not Call Registry. |", "$ref": "#\/components\/schemas\/DoNotCallSource" }, "note": { "type": [ "string", "null" ] }, "removable": { "type": "boolean", "description": "Whether the entry can be removed. People who asked not to be called never can." }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "livemode", "phone_number", "source", "note", "removable", "created_at" ], "title": "DoNotCallEntryResource" }, "DoNotCallSource": { "type": "string", "description": "| |\n|---|\n| `opt_out` The person asked not to be called: on an AI call, to a GH Live agent, or to the client. |\n| `manual` Added by GH staff or the client. |\n| `national_registry` Imported from the FTC National Do Not Call Registry. |", "enum": [ "opt_out", "manual", "national_registry" ], "title": "DoNotCallSource" }, "IntegrationProvider": { "type": "string", "description": "The calendars and field-service CRMs a client can connect for booking and lead sync.\n", "enum": [ "google_calendar", "microsoft_calendar", "jobber", "housecall_pro", "servicetitan", "acuity" ], "title": "IntegrationProvider" }, "LeadResource": { "type": "object", "properties": { "id": { "type": "integer" }, "livemode": { "type": "boolean", "description": "`true` for live data, `false` for test data (created with a `vk_test_` key)." }, "name": { "type": [ "string", "null" ], "examples": [ "Maria Rivera" ] }, "phone_number": { "type": [ "string", "null" ], "examples": [ "+15125550123" ] }, "email": { "type": [ "string", "null" ], "examples": [ "maria@example.com" ] }, "reason": { "type": "string", "description": "Why they got in touch. Not included for HIPAA-mode accounts." }, "urgency": { "type": [ "string", "null" ], "examples": [ "high" ] }, "details": { "type": [ "object", "null" ], "description": "Extra fields captured with the lead. Not included for HIPAA-mode accounts.", "additionalProperties": {} }, "custom_fields": { "type": "object", "description": "The custom fields the AI collected, as `{key: {label, value}}`. Not included for HIPAA-mode accounts." }, "source": { "type": "string", "description": "Where the lead came from.", "enum": [ "api", "call", "chat", "outbound_call", "website" ] }, "call_id": { "type": [ "integer", "null" ] }, "chat_id": { "type": [ "integer", "null" ] }, "outbound_call_id": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "livemode", "name", "phone_number", "email", "urgency", "source", "call_id", "chat_id", "outbound_call_id", "created_at" ], "title": "LeadResource" }, "OutboundCallResource": { "type": "object", "properties": { "id": { "type": "integer" }, "livemode": { "type": "boolean", "description": "`true` for live data, `false` for test data (created with a `vk_test_` key)." }, "source": { "description": "What started the call: your system (`api`), a speed-to-lead callback, a campaign or an agent.\n| |\n|---|\n| `speed_to_lead` The AI calls back someone who just asked to be contacted. |\n| `agent_dial` A GH Live agent dials a number by hand from the workspace. |\n| `campaign` The AI works through a client's campaign contact list. |\n| `api` The client's own system queued an AI call through the public API or platform MCP server. |", "$ref": "#\/components\/schemas\/OutboundSource" }, "purpose": { "description": "`marketing` needs marketing consent; `informational` covers reminders and follow-ups the person asked for.", "$ref": "#\/components\/schemas\/CallPurpose" }, "status": { "$ref": "#\/components\/schemas\/OutboundCallStatus" }, "contact_name": { "type": [ "string", "null" ], "examples": [ "Maria Rivera" ] }, "phone_number": { "type": "string", "examples": [ "+15125550123" ] }, "blocked_reason": { "type": [ "string", "null" ], "description": "Why the call was blocked or delayed, as a code." }, "blocked_reason_message": { "type": [ "string", "null" ], "description": "Why the call was blocked or delayed, in words." }, "scheduled_for": { "type": [ "string", "null" ], "description": "When a delayed call is due to ring (calling hours, daily limit)." }, "attempts": { "type": "integer" }, "answered_at": { "type": [ "string", "null" ] }, "answered_by": { "anyOf": [ { "description": "Who picked up, from answering machine detection: `human`, `machine` or `unknown`. `null` when there was no result (not answered, or an agent's call).", "$ref": "#\/components\/schemas\/AnsweredBy" }, { "type": "null" } ] }, "voicemail_left_at": { "type": [ "string", "null" ], "description": "When the AI finished leaving a message on voicemail, under the account's \"leave a message\" setting." }, "ended_at": { "type": [ "string", "null" ] }, "duration_seconds": { "type": [ "integer", "null" ] }, "summary": { "type": [ "string", "null" ], "description": "The AI's summary of the call. Not included for HIPAA-mode accounts." }, "transcript": { "type": [ "array", "null" ], "description": "The conversation, turn by turn. Only on `GET \/outbound-calls\/{id}`, and never for HIPAA-mode accounts.", "items": { "type": "object", "properties": { "role": { "type": "string" }, "text": { "type": "string" } }, "required": [ "role", "text" ] } }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "livemode", "source", "purpose", "status", "contact_name", "phone_number", "blocked_reason", "blocked_reason_message", "scheduled_for", "attempts", "answered_at", "answered_by", "voicemail_left_at", "ended_at", "duration_seconds", "created_at" ], "title": "OutboundCallResource" }, "OutboundCallStatus": { "type": "string", "enum": [ "queued", "scheduled", "blocked", "connecting_agent", "dialing", "in_progress", "completed", "no_answer", "voicemail", "failed" ], "title": "OutboundCallStatus" }, "OutboundSource": { "type": "string", "description": "| |\n|---|\n| `speed_to_lead` The AI calls back someone who just asked to be contacted. |\n| `agent_dial` A GH Live agent dials a number by hand from the workspace. |\n| `campaign` The AI works through a client's campaign contact list. |\n| `api` The client's own system queued an AI call through the public API or platform MCP server. |", "enum": [ "speed_to_lead", "agent_dial", "campaign", "api" ], "title": "OutboundSource" }, "RoutingAction": { "type": "string", "enum": [ "ai_agent", "human_queue", "forward_number", "voicemail" ], "title": "RoutingAction" }, "StoreBlockedCallerRequest": { "type": "object", "properties": { "pattern": { "type": "string", "description": "A US phone number in any common format, or a prefix of at least four digits ending in `*` to block\nevery number starting with it.", "maxLength": 32 }, "note": { "type": [ "string", "null" ], "examples": [ "Robocaller" ], "maxLength": 255 } }, "required": [ "pattern" ], "title": "StoreBlockedCallerRequest" }, "StoreChatMessageRequest": { "type": "object", "properties": { "body": { "type": "string", "description": "The reply, as plain text. The visitor sees it from \"Team\".", "examples": [ "Thanks for waiting! We have an opening on Thursday at 3pm. Shall I hold it for you?" ], "maxLength": 2000 } }, "required": [ "body" ], "title": "StoreChatMessageRequest" }, "StoreDoNotCallEntryRequest": { "type": "object", "properties": { "phone_number": { "type": "string", "maxLength": 32 }, "note": { "type": [ "string", "null" ], "examples": [ "Asked us to stop calling" ], "maxLength": 500 }, "opted_out": { "type": "boolean", "description": "The person asked not to be called. Recorded as a permanent opt-out that can never be\nremoved, and any AI-call consent they gave is revoked." } }, "required": [ "phone_number" ], "title": "StoreDoNotCallEntryRequest" }, "StoreLeadRequest": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "examples": [ "Maria Rivera" ], "maxLength": 255 }, "phone_number": { "type": [ "string", "null" ], "description": "A US phone number in any common format. Needed for a callback.", "maxLength": 32 }, "email": { "type": [ "string", "null" ], "format": "email", "examples": [ "maria@example.com" ], "maxLength": 255 }, "reason": { "type": "string", "description": "Why they got in touch.", "examples": [ "Wants a quote for a water heater replacement" ], "maxLength": 2000 }, "urgency": { "type": [ "string", "null" ], "examples": [ "high" ], "maxLength": 50 }, "details": { "type": [ "array", "null" ], "description": "Any extra fields you want to keep with the lead (up to 50 keys).", "items": { "type": "string" }, "maxItems": 50 }, "callback": { "type": "object", "description": "Ask the AI to call the person back now (speed-to-lead). Only send this when the person\nagreed to an AI call: `consent_text` must be the exact wording they agreed to. Needs the\n`outbound:write` scope as well as `leads:write`.", "properties": { "consent_text": { "type": "string", "examples": [ "I agree to receive an automated AI phone call from Rivera Plumbing about my request." ], "minLength": 20, "maxLength": 2000 }, "source_url": { "type": [ "string", "null" ], "format": "uri", "description": "The page where they agreed.", "maxLength": 2048 }, "ip_address": { "type": [ "string", "null" ], "description": "Their IP address when they agreed." }, "user_agent": { "type": [ "string", "null" ], "description": "Their browser's user agent when they agreed.", "maxLength": 512 } } } }, "required": [ "reason" ], "title": "StoreLeadRequest" }, "StoreOutboundCallRequest": { "type": "object", "properties": { "phone_number": { "type": "string", "description": "The US number to call. It needs AI-call consent on record and must not be on a Do Not Call list.", "examples": [ "+15125550123" ], "maxLength": 32 }, "contact_name": { "type": [ "string", "null" ], "examples": [ "Maria Rivera" ], "maxLength": 255 }, "purpose": { "anyOf": [ { "description": "`marketing` (the default) needs marketing consent. `informational` is for reminders and\nfollow-ups the person asked for, and the only purpose HIPAA-mode accounts may use.", "$ref": "#\/components\/schemas\/CallPurpose" }, { "type": "null" } ] }, "context": { "type": [ "array", "null" ], "description": "Anything the AI should know for the call, like the service they asked about (up to 20 keys).", "examples": [ { "service": "Water heater replacement", "preferred_time": "mornings" } ], "items": { "type": "string" }, "maxItems": 20 } }, "required": [ "phone_number" ], "title": "StoreOutboundCallRequest" }, "StoreWebhookEndpointRequest": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "A public HTTPS URL.", "examples": [ "https:\/\/hooks.example.com\/vocenya" ], "maxLength": 2048 }, "events": { "type": "array", "description": "The events to send, at least one. The key needs the read scope of each event's record:\n`lead.created` needs `leads:read`, `call.completed` needs `calls:read`, `booking.created`\nneeds `bookings:read`, `outbound_call.completed` needs `outbound:write`, every `chat.*`\nevent needs `chats:read`, and `chat.lead_captured` also needs `leads:read`.", "items": { "$ref": "#\/components\/schemas\/WebhookEvent" }, "minItems": 1 }, "description": { "type": [ "string", "null" ], "examples": [ "Our CRM" ], "maxLength": 255 } }, "required": [ "url", "events" ], "title": "StoreWebhookEndpointRequest" }, "TestWebhookEndpointRequest": { "type": "object", "properties": { "event": { "anyOf": [ { "description": "Send a sample of this event (made-up data plus `\"sample\": true`) instead of `webhook.test`.", "examples": [ "chat.message.created" ], "$ref": "#\/components\/schemas\/WebhookEvent" }, { "type": "null" } ] } }, "title": "TestWebhookEndpointRequest" }, "WebhookDeliveryResource": { "type": "object", "properties": { "id": { "type": "integer" }, "livemode": { "type": "boolean", "description": "`true` for live data, `false` for test data (created with a `vk_test_` key)." }, "event_id": { "type": "string", "description": "The event id, also sent as the `Vocenya-Delivery` header. Use it to ignore duplicates." }, "event": { "type": "string", "examples": [ "lead.created" ] }, "webhook_endpoint_id": { "type": "integer" }, "status": { "$ref": "#\/components\/schemas\/WebhookDeliveryStatus" }, "attempts": { "type": "integer" }, "response_status": { "type": [ "integer", "null" ] }, "last_error": { "type": [ "string", "null" ] }, "next_attempt_at": { "type": [ "string", "null" ] }, "delivered_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "livemode", "event_id", "event", "webhook_endpoint_id", "status", "attempts", "response_status", "last_error", "next_attempt_at", "delivered_at", "created_at" ], "title": "WebhookDeliveryResource" }, "WebhookDeliveryStatus": { "type": "string", "description": "| |\n|---|\n| `pending` Waiting for its first or next attempt. |\n| `delivered` The endpoint answered with a 2xx status. |\n| `failed` Every attempt failed, or the endpoint was unsafe to call. |", "enum": [ "pending", "delivered", "failed" ], "title": "WebhookDeliveryStatus" }, "WebhookEndpointResource": { "type": "object", "properties": { "id": { "type": "integer" }, "livemode": { "type": "boolean", "description": "`true` for live data, `false` for test data (created with a `vk_test_` key)." }, "url": { "type": "string", "examples": [ "https:\/\/hooks.example.com\/vocenya" ] }, "description": { "type": [ "string", "null" ] }, "events": { "type": "array", "description": "The events sent to this endpoint.", "items": { "$ref": "#\/components\/schemas\/WebhookEvent" } }, "enabled": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "livemode", "url", "description", "events", "enabled", "created_at" ], "title": "WebhookEndpointResource" }, "WebhookEvent": { "type": "string", "description": "Events a client can subscribe a webhook endpoint to.\n", "enum": [ "lead.created", "call.completed", "booking.created", "chat.handed_off", "outbound_call.completed", "chat.started", "chat.message.created", "chat.lead_captured", "chat.handoff_requested", "chat.closed" ], "title": "WebhookEvent" } }, "responses": { "ValidationException": { "description": "Validation error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } } } } }