{ "components": { "schemas": { "AssistantListResponseV1": { "description": "Every assistant in the workspace. Small, so it is not paged.", "properties": { "assistants": { "items": { "$ref": "#/components/schemas/AssistantSummaryV1" }, "title": "Assistants", "type": "array" } }, "required": [ "assistants" ], "title": "AssistantListResponseV1", "type": "object" }, "AssistantSummaryV1": { "description": "What a client needs to know to place a call with this assistant.", "properties": { "assistant_id": { "title": "Assistant Id", "type": "string" }, "assistant_name": { "title": "Assistant Name", "type": "string" }, "call_variables": { "description": "Placeholder names this assistant's outbound prompt expects, e.g. ['hotel_name', 'guest_name']. Pass them as `call_variables` on POST /v1/calls. Variables Voicetta fills in itself are not listed.", "items": { "type": "string" }, "title": "Call Variables", "type": "array" }, "phone_numbers": { "items": { "$ref": "#/components/schemas/OutboundPhoneNumberV1" }, "title": "Phone Numbers", "type": "array" }, "workspace_id": { "title": "Workspace Id", "type": "string" } }, "required": [ "assistant_id", "assistant_name", "workspace_id", "phone_numbers", "call_variables" ], "title": "AssistantSummaryV1", "type": "object" }, "CallAnalysis": { "properties": { "intent": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Intent" }, "outcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Outcome" }, "sentiment": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sentiment" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary" } }, "title": "CallAnalysis", "type": "object" }, "CallCosts": { "properties": { "base": { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "title": "Base", "type": "string" }, "charged": { "anyOf": [ { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" }, { "type": "null" } ], "title": "Charged" }, "currency": { "default": "USD", "title": "Currency", "type": "string" }, "language_model": { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "title": "Language Model", "type": "string" }, "livekit": { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "title": "Livekit", "type": "string" }, "speech_to_text": { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "title": "Speech To Text", "type": "string" }, "telephony": { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "title": "Telephony", "type": "string" }, "text_to_speech": { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "title": "Text To Speech", "type": "string" }, "total": { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "title": "Total", "type": "string" } }, "required": [ "base", "livekit", "telephony", "speech_to_text", "language_model", "text_to_speech", "total" ], "title": "CallCosts", "type": "object" }, "CallCustomer": { "properties": { "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country" }, "customer_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Customer Id" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone" } }, "title": "CallCustomer", "type": "object" }, "CallDetailResponseV1": { "description": "A single call.", "properties": { "call": { "$ref": "#/components/schemas/CallPayloadV1" } }, "required": [ "call" ], "title": "CallDetailResponseV1", "type": "object" }, "CallEvaluation": { "properties": { "evaluation_id": { "title": "Evaluation Id", "type": "string" }, "initial_result": { "title": "Initial Result", "type": "string" }, "rationale": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rationale" }, "recovered": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Recovered" }, "result": { "title": "Result", "type": "string" }, "title": { "title": "Title", "type": "string" } }, "required": [ "evaluation_id", "title", "result", "initial_result" ], "title": "CallEvaluation", "type": "object" }, "CallFollowUp": { "properties": { "channel": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Channel" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" }, "sent_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Sent At" }, "status": { "title": "Status", "type": "string" } }, "required": [ "status" ], "title": "CallFollowUp", "type": "object" }, "CallListResponseV1": { "description": "One page of calls, newest first.", "properties": { "calls": { "items": { "$ref": "#/components/schemas/CallPayloadV1" }, "title": "Calls", "type": "array" }, "has_more": { "description": "True when a further page is available. Loop on this, not on next_cursor.", "title": "Has More", "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor for the next page. Pass it back unchanged as `cursor`. Absent on the last page.", "title": "Next Cursor" } }, "required": [ "calls", "has_more" ], "title": "CallListResponseV1", "type": "object" }, "CallPayloadV1": { "description": "The `call` object inside a delivery. Only `call`-group fields are required.", "properties": { "analysis": { "anyOf": [ { "$ref": "#/components/schemas/CallAnalysis" }, { "type": "null" } ] }, "assistant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assistant Id" }, "assistant_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assistant Name" }, "call_id": { "title": "Call Id", "type": "string" }, "call_type": { "title": "Call Type", "type": "string" }, "call_variables": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Call Variables" }, "config_snapshot": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Config Snapshot" }, "costs": { "anyOf": [ { "$ref": "#/components/schemas/CallCosts" }, { "type": "null" } ] }, "customer": { "anyOf": [ { "$ref": "#/components/schemas/CallCustomer" }, { "type": "null" } ] }, "direction": { "title": "Direction", "type": "string" }, "duration_seconds": { "title": "Duration Seconds", "type": "integer" }, "end_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End Reason" }, "ended_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Ended At" }, "evaluations": { "anyOf": [ { "items": { "$ref": "#/components/schemas/CallEvaluation" }, "type": "array" }, { "type": "null" } ], "title": "Evaluations" }, "follow_ups": { "anyOf": [ { "items": { "$ref": "#/components/schemas/CallFollowUp" }, "type": "array" }, { "type": "null" } ], "title": "Follow Ups" }, "is_test": { "default": false, "title": "Is Test", "type": "boolean" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "performance_metrics": { "anyOf": [ { "$ref": "#/components/schemas/CallPerformanceMetrics" }, { "type": "null" } ] }, "recording": { "anyOf": [ { "$ref": "#/components/schemas/CallRecording" }, { "type": "null" } ] }, "started_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Started At" }, "status": { "title": "Status", "type": "string" }, "transcript": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Transcript" }, "workspace_id": { "title": "Workspace Id", "type": "string" } }, "required": [ "call_id", "workspace_id", "call_type", "direction", "status", "duration_seconds" ], "title": "CallPayloadV1", "type": "object" }, "CallPerformanceMetrics": { "properties": { "end_of_utterance": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "End Of Utterance" }, "language_model": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Language Model" }, "speech_to_text": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Speech To Text" }, "text_to_speech": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Text To Speech" }, "voice_activity": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Voice Activity" } }, "title": "CallPerformanceMetrics", "type": "object" }, "CallRecording": { "properties": { "available": { "default": false, "title": "Available", "type": "boolean" }, "download_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Download Url" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, "title": "CallRecording", "type": "object" }, "CallRecordingResponseV1": { "description": "A signed link to one call's audio.\n\nA body rather than a redirect, so a client decides when to follow it. A\nbrowser would follow a redirect on its own, with the API key request behind\nit, which is not something a public docs page should be able to trigger.", "properties": { "call_id": { "title": "Call Id", "type": "string" }, "url": { "description": "Signed audio URL. Expires within the hour. Fetch this endpoint again for a fresh one rather than storing it.", "title": "Url", "type": "string" } }, "required": [ "call_id", "url" ], "title": "CallRecordingResponseV1", "type": "object" }, "CallWebhookPayloadV1": { "description": "The full request body we POST to a partner endpoint.", "properties": { "call": { "$ref": "#/components/schemas/CallPayloadV1" }, "event": { "title": "Event", "type": "string" }, "event_id": { "title": "Event Id", "type": "string" }, "occurred_at": { "format": "date-time", "title": "Occurred At", "type": "string" }, "version": { "default": 1, "title": "Version", "type": "integer" } }, "required": [ "event", "event_id", "occurred_at", "call" ], "title": "CallWebhookPayloadV1", "type": "object" }, "CreateCallRequestV1": { "description": "A request to call one number with one assistant.", "properties": { "assistant_id": { "description": "The assistant to handle the call. Copy it from Agent in the dashboard, or from GET /v1/assistants.", "format": "uuid", "title": "Assistant Id", "type": "string" }, "call_variables": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Values for this one call, substituted into {{placeholders}} in the assistant's prompt and greeting. Keys must start with a letter and contain only letters, digits and underscores.", "title": "Call Variables" }, "customer_name": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Name of the person being called. Available to the prompt as {{participant_name}}.", "title": "Customer Name" }, "from": { "anyOf": [ { "maxLength": 20, "type": "string" }, { "type": "null" } ], "description": "Number to call from, in E.164 format. Optional when the assistant has exactly one number enabled for outbound calls.", "title": "From" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Opaque JSON stored with the call and returned unchanged. Never interpreted by Voicetta. At most 8192 bytes.", "title": "Metadata" }, "to": { "description": "Number to call, in E.164 format, e.g. +14155559999.", "maxLength": 20, "title": "To", "type": "string" } }, "required": [ "assistant_id", "to" ], "title": "CreateCallRequestV1", "type": "object" }, "CreateCallResponseV1": { "description": "The accepted call.\n\n`call` is the same object the read API and the webhooks deliver, so one\nhandler can consume all three. At this point it carries only the `call` and\n`customer` groups \u2014 there is no transcript to report yet.", "properties": { "call": { "$ref": "#/components/schemas/CallPayloadV1" } }, "required": [ "call" ], "title": "CreateCallResponseV1", "type": "object" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "title": "Detail", "type": "array" } }, "title": "HTTPValidationError", "type": "object" }, "MessageCosts": { "description": "Indicative per-message rate, not a billed amount.\n\nUnlike `CallCosts.charged`, nothing here is debited from the wallet and\nnothing reconciles against an invoice: text is priced at a flat per-channel\nrate applied at read time.", "properties": { "currency": { "default": "USD", "title": "Currency", "type": "string" }, "message_cost": { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "title": "Message Cost", "type": "string" } }, "required": [ "message_cost" ], "title": "MessageCosts", "type": "object" }, "MessageDetailResponseV1": { "description": "A single message.", "properties": { "message": { "$ref": "#/components/schemas/MessagePayloadV1" } }, "required": [ "message" ], "title": "MessageDetailResponseV1", "type": "object" }, "MessageListResponseV1": { "description": "One page of SMS and WhatsApp messages, newest first.", "properties": { "has_more": { "description": "True when a further page is available. Loop on this, not on next_cursor.", "title": "Has More", "type": "boolean" }, "messages": { "items": { "$ref": "#/components/schemas/MessagePayloadV1" }, "title": "Messages", "type": "array" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor for the next page. Pass it back unchanged as `cursor`. Absent on the last page.", "title": "Next Cursor" } }, "required": [ "messages", "has_more" ], "title": "MessageListResponseV1", "type": "object" }, "MessagePayloadV1": { "description": "The `message` object inside a delivery. Only identity fields are required.", "properties": { "assistant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assistant Id" }, "assistant_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assistant Name" }, "channel": { "title": "Channel", "type": "string" }, "content": { "title": "Content", "type": "string" }, "costs": { "anyOf": [ { "$ref": "#/components/schemas/MessageCosts" }, { "type": "null" } ] }, "customer": { "anyOf": [ { "$ref": "#/components/schemas/CallCustomer" }, { "type": "null" } ] }, "direction": { "title": "Direction", "type": "string" }, "message_id": { "title": "Message Id", "type": "string" }, "occurred_at": { "format": "date-time", "title": "Occurred At", "type": "string" }, "provider_message_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider Message Id" }, "reply": { "anyOf": [ { "$ref": "#/components/schemas/MessageReply" }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source" }, "thread_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Thread Id" }, "workspace_id": { "title": "Workspace Id", "type": "string" } }, "required": [ "message_id", "workspace_id", "channel", "direction", "occurred_at", "content" ], "title": "MessagePayloadV1", "type": "object" }, "MessageReply": { "description": "The assistant's answer, sent in the same turn as an inbound message.", "properties": { "content": { "title": "Content", "type": "string" }, "provider_message_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider Message Id" }, "timestamp": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Timestamp" } }, "required": [ "content" ], "title": "MessageReply", "type": "object" }, "MessageWebhookPayloadV1": { "description": "The full request body we POST to a partner endpoint.", "properties": { "event": { "title": "Event", "type": "string" }, "event_id": { "title": "Event Id", "type": "string" }, "message": { "$ref": "#/components/schemas/MessagePayloadV1" }, "occurred_at": { "format": "date-time", "title": "Occurred At", "type": "string" }, "version": { "default": 1, "title": "Version", "type": "integer" } }, "required": [ "event", "event_id", "occurred_at", "message" ], "title": "MessageWebhookPayloadV1", "type": "object" }, "OutboundPhoneNumberV1": { "description": "One number an assistant owns, and whether it can dial out.", "properties": { "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country" }, "outbound_enabled": { "description": "Whether this number can originate calls. False until outbound is enabled for it in the dashboard.", "title": "Outbound Enabled", "type": "boolean" }, "phone_number": { "title": "Phone Number", "type": "string" } }, "required": [ "phone_number", "outbound_enabled" ], "title": "OutboundPhoneNumberV1", "type": "object" }, "ThreadCosts": { "description": "Indicative total for the thread, not a billed amount.\n\nThe same flat per-channel rate the message events report, summed over the\nassistant's messages. Nothing here is debited from the wallet.", "properties": { "charged_message_count": { "title": "Charged Message Count", "type": "integer" }, "currency": { "default": "USD", "title": "Currency", "type": "string" }, "total": { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "title": "Total", "type": "string" } }, "required": [ "total", "charged_message_count" ], "title": "ThreadCosts", "type": "object" }, "ThreadDetailResponseV1": { "description": "A single completed conversation.", "properties": { "thread": { "$ref": "#/components/schemas/ThreadPayloadV1" } }, "required": [ "thread" ], "title": "ThreadDetailResponseV1", "type": "object" }, "ThreadListResponseV1": { "description": "One page of completed SMS and WhatsApp conversations, newest first.", "properties": { "has_more": { "description": "True when a further page is available. Loop on this, not on next_cursor.", "title": "Has More", "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor for the next page. Pass it back unchanged as `cursor`. Absent on the last page.", "title": "Next Cursor" }, "threads": { "items": { "$ref": "#/components/schemas/ThreadPayloadV1" }, "title": "Threads", "type": "array" } }, "required": [ "threads", "has_more" ], "title": "ThreadListResponseV1", "type": "object" }, "ThreadPayloadV1": { "description": "The `thread` object inside a delivery. Only identity fields are required.", "properties": { "analysis": { "anyOf": [ { "$ref": "#/components/schemas/CallAnalysis" }, { "type": "null" } ] }, "anchor_message_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Anchor Message Id" }, "assistant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assistant Id" }, "assistant_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assistant Name" }, "channel": { "title": "Channel", "type": "string" }, "close_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Close Reason" }, "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Completed At" }, "costs": { "anyOf": [ { "$ref": "#/components/schemas/ThreadCosts" }, { "type": "null" } ] }, "customer": { "anyOf": [ { "$ref": "#/components/schemas/CallCustomer" }, { "type": "null" } ] }, "evaluations": { "anyOf": [ { "items": { "$ref": "#/components/schemas/CallEvaluation" }, "type": "array" }, { "type": "null" } ], "title": "Evaluations" }, "follow_ups": { "anyOf": [ { "items": { "$ref": "#/components/schemas/CallFollowUp" }, "type": "array" }, { "type": "null" } ], "title": "Follow Ups" }, "last_message_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Last Message At" }, "message_count": { "default": 0, "title": "Message Count", "type": "integer" }, "started_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Started At" }, "thread_id": { "title": "Thread Id", "type": "string" }, "transcript": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Transcript" }, "workspace_id": { "title": "Workspace Id", "type": "string" } }, "required": [ "thread_id", "workspace_id", "channel" ], "title": "ThreadPayloadV1", "type": "object" }, "ThreadWebhookPayloadV1": { "description": "The full request body we POST to a partner endpoint.", "properties": { "event": { "title": "Event", "type": "string" }, "event_id": { "title": "Event Id", "type": "string" }, "occurred_at": { "format": "date-time", "title": "Occurred At", "type": "string" }, "thread": { "$ref": "#/components/schemas/ThreadPayloadV1" }, "version": { "default": 1, "title": "Version", "type": "integer" } }, "required": [ "event", "event_id", "occurred_at", "thread" ], "title": "ThreadWebhookPayloadV1", "type": "object" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "title": "Location", "type": "array" }, "msg": { "title": "Message", "type": "string" }, "type": { "title": "Error Type", "type": "string" } }, "required": [ "loc", "msg", "type" ], "title": "ValidationError", "type": "object" } }, "securitySchemes": { "PartnerApiKey": { "description": "A workspace API key from Settings > Developers, e.g. `vk_live_...`.", "scheme": "bearer", "type": "http" } } }, "info": { "contact": { "name": "Voicetta developer docs", "url": "https://voicetta.com/developers" }, "description": "Start phone calls from your own product, read the conversations your Voicetta\nassistants handled \u2014 voice calls, SMS and WhatsApp messages, and graded text\nthreads \u2014 and receive each one as a webhook the moment it happens.\n\nAuthenticate every request with a workspace API key as\n`Authorization: Bearer `. Keys are created in the Voicetta dashboard under\nSettings > Developers and are scoped to one workspace, so a request can only\never return that workspace's conversations.\n\n`POST /v1/calls` additionally requires the `outbound_calls` permission on the\nkey, which is off by default: being able to read a call and being able to place\none are separate decisions, and the second spends money. Send an\n`Idempotency-Key` header with it so a retry after a timeout returns the original\ncall rather than dialling a real person twice.\n\nNull fields are omitted from responses rather than sent as `null`. Treat a\nmissing key as \"no value\", not as an error.\n\nGuides, dynamic variable reference, webhook payloads and HMAC verification\nexamples: https://voicetta.com/developers", "title": "Voicetta API", "version": "1.0.0" }, "openapi": "3.1.0", "paths": { "/v1/assistants": { "get": { "description": "Everything needed to place a call: ids, numbers and prompt variables.", "operationId": "list_workspace_assistants_v1_assistants_get", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantListResponseV1" } } }, "description": "Successful Response" }, "401": { "description": "Missing, malformed, unknown, or revoked API key" }, "503": { "description": "The partner API is disabled for this deployment" } }, "security": [ { "PartnerApiKey": [] } ], "summary": "List assistants", "tags": [ "Assistants" ] } }, "/v1/calls": { "get": { "description": "Calls newest first. Page with `next_cursor` until `has_more` is false.", "operationId": "list_workspace_calls_v1_calls_get", "parameters": [ { "description": "Cursor from a previous page", "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor from a previous page", "title": "Cursor" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Only calls that ended at or after this time (ISO 8601)", "in": "query", "name": "from", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Only calls that ended at or after this time (ISO 8601)", "title": "From" } }, { "description": "Only calls that ended at or before this time (ISO 8601)", "in": "query", "name": "to", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Only calls that ended at or before this time (ISO 8601)", "title": "To" } }, { "description": "Only calls handled by this assistant", "in": "query", "name": "assistant_id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Only calls handled by this assistant", "title": "Assistant Id" } }, { "description": "Include test calls", "in": "query", "name": "include_test", "required": false, "schema": { "default": false, "description": "Include test calls", "title": "Include Test", "type": "boolean" } }, { "description": "Comma-separated field groups to narrow the response. You can only request groups granted on the API key. Defaults to the key's allowlist. Available groups: call, customer, transcript, analysis, evaluations, recording, costs, performance_metrics, config_snapshot, follow_ups", "in": "query", "name": "fields", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated field groups to narrow the response. You can only request groups granted on the API key. Defaults to the key's allowlist. Available groups: call, customer, transcript, analysis, evaluations, recording, costs, performance_metrics, config_snapshot, follow_ups", "title": "Fields" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallListResponseV1" } } }, "description": "Successful Response" }, "400": { "description": "Invalid cursor, or an unknown name in `fields`" }, "401": { "description": "Missing, malformed, unknown, or revoked API key" }, "403": { "description": "The API key is not permitted to access the requested field groups" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "503": { "description": "The partner API is disabled for this deployment" } }, "security": [ { "PartnerApiKey": [] } ], "summary": "List calls", "tags": [ "Calls" ] }, "post": { "description": "Call `to` with `assistant_id`, and return a `call_id` to follow it by.\n\nReturns as soon as the call is accepted rather than when it connects, so\nthe response is fast and the outcome is observed through `status` on\n`GET /v1/calls/{call_id}` or through the `call.started` and `call.completed`\nwebhooks. A call moves `queued` -> `in_progress` -> `ended`, or to `error`\nif it could not be placed.", "operationId": "create_outbound_call_v1_calls_post", "parameters": [ { "description": "A unique string of your choosing, e.g. a UUID. If the same key is sent again for this workspace, the original call is returned and no second call is placed. Send one on every request: a timed-out POST may already have started dialling.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "A unique string of your choosing, e.g. a UUID. If the same key is sent again for this workspace, the original call is returned and no second call is placed. Send one on every request: a timed-out POST may already have started dialling.", "title": "Idempotency-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCallRequestV1" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCallResponseV1" } } }, "description": "The call was accepted and is being placed" }, "400": { "description": "The destination is not a valid E.164 number, a `call_variables` key was rejected, `metadata` is too large, the assistant has no number enabled for outbound calls, or it has several and `from` was omitted" }, "401": { "description": "Missing, malformed, unknown, or revoked API key" }, "403": { "description": "The API key does not have the `outbound_calls` scope, or calls to the destination country are not permitted from this number" }, "404": { "description": "No such assistant or phone number in this workspace" }, "409": { "description": "The wallet balance is too low, or the assistant is already at its concurrent call limit. Retryable once the condition clears." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Too many calls started for this workspace" }, "502": { "description": "The telephony provider rejected the call. The call is marked `error`." }, "503": { "description": "Placing calls through the API is disabled for this deployment" } }, "security": [ { "PartnerApiKey": [] } ], "summary": "Start a call", "tags": [ "Calls" ] } }, "/v1/calls/{call_id}": { "get": { "description": "The same call object the webhook delivers, fetched on demand.\n\nWorks for a call that has not finished yet, which is what makes\n`POST /v1/calls` pollable: the conversation is written on hangup, so before\nthen the answer comes from the queued call instead, with the same shape and\nthe groups that cannot exist yet left out.", "operationId": "get_workspace_call_v1_calls__call_id__get", "parameters": [ { "in": "path", "name": "call_id", "required": true, "schema": { "format": "uuid", "title": "Call Id", "type": "string" } }, { "description": "Comma-separated field groups to narrow the response. You can only request groups granted on the API key. Defaults to the key's allowlist. Available groups: call, customer, transcript, analysis, evaluations, recording, costs, performance_metrics, config_snapshot, follow_ups", "in": "query", "name": "fields", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated field groups to narrow the response. You can only request groups granted on the API key. Defaults to the key's allowlist. Available groups: call, customer, transcript, analysis, evaluations, recording, costs, performance_metrics, config_snapshot, follow_ups", "title": "Fields" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallDetailResponseV1" } } }, "description": "Successful Response" }, "400": { "description": "Unknown name in `fields`" }, "401": { "description": "Missing, malformed, unknown, or revoked API key" }, "403": { "description": "The API key is not permitted to access the requested field groups" }, "404": { "description": "No such call in this workspace" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "503": { "description": "The partner API is disabled for this deployment" } }, "security": [ { "PartnerApiKey": [] } ], "summary": "Get call", "tags": [ "Calls" ] } }, "/v1/calls/{call_id}/recording": { "get": { "description": "Return a freshly signed storage URL.\n\nThe webhook payload points here rather than carrying a signed URL directly,\nbecause signed URLs expire within the hour and would rot inside a stored\npayload. Each request mints a new one.\n\nA JSON body rather than a redirect: browsers follow redirects on their own,\nwhich would send a partner's API-key request straight at storage from any\npage that called this, including the public API reference.", "operationId": "get_call_recording_v1_calls__call_id__recording_get", "parameters": [ { "in": "path", "name": "call_id", "required": true, "schema": { "format": "uuid", "title": "Call Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallRecordingResponseV1" } } }, "description": "A freshly signed audio URL. It expires within the hour, so fetch it when you need it rather than storing it." }, "401": { "description": "Missing, malformed, unknown, or revoked API key" }, "403": { "description": "The API key is not permitted to access recordings" }, "404": { "description": "No such call in this workspace, or it has no recording" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "503": { "description": "Recording storage is temporarily unavailable" } }, "security": [ { "PartnerApiKey": [] } ], "summary": "Get call recording", "tags": [ "Calls" ] } }, "/v1/messages": { "get": { "description": "Messages newest first. Page with `next_cursor` until `has_more` is false.\n\nEvery message the webhook pushed is here under the same id, which is what\nmakes push the convenience and pull the guarantee.", "operationId": "list_workspace_messages_v1_messages_get", "parameters": [ { "description": "Cursor from a previous page", "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor from a previous page", "title": "Cursor" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Only messages at or after this time (ISO 8601)", "in": "query", "name": "from", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Only messages at or after this time (ISO 8601)", "title": "From" } }, { "description": "Only messages at or before this time (ISO 8601)", "in": "query", "name": "to", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Only messages at or before this time (ISO 8601)", "title": "To" } }, { "description": "Only messages handled by this assistant", "in": "query", "name": "assistant_id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Only messages handled by this assistant", "title": "Assistant Id" } }, { "description": "Restrict to one channel: sms, whatsapp", "in": "query", "name": "channel", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Restrict to one channel: sms, whatsapp", "title": "Channel" } }, { "description": "Restrict to one direction: inbound, outbound", "in": "query", "name": "direction", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Restrict to one direction: inbound, outbound", "title": "Direction" } }, { "description": "Only messages belonging to this conversation thread", "in": "query", "name": "thread_id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Only messages belonging to this conversation thread", "title": "Thread Id" } }, { "description": "Comma-separated field groups to narrow the response. You can only request groups granted on the API key. Defaults to the key's allowlist. A message payload can carry: call, customer, costs. Groups that belong to a completed conversation rather than a single message are omitted rather than returned empty.", "in": "query", "name": "fields", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated field groups to narrow the response. You can only request groups granted on the API key. Defaults to the key's allowlist. A message payload can carry: call, customer, costs. Groups that belong to a completed conversation rather than a single message are omitted rather than returned empty.", "title": "Fields" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageListResponseV1" } } }, "description": "Successful Response" }, "400": { "description": "Invalid cursor, unknown `fields`, `channel` or `direction`" }, "401": { "description": "Missing, malformed, unknown, or revoked API key" }, "403": { "description": "The API key is not permitted to access the requested field groups" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "503": { "description": "The partner API is disabled for this deployment" } }, "security": [ { "PartnerApiKey": [] } ], "summary": "List messages", "tags": [ "Messages" ] } }, "/v1/messages/{message_id}": { "get": { "description": "The same message object the webhook delivers, fetched on demand.", "operationId": "get_workspace_message_v1_messages__message_id__get", "parameters": [ { "in": "path", "name": "message_id", "required": true, "schema": { "format": "uuid", "title": "Message Id", "type": "string" } }, { "description": "Comma-separated field groups to narrow the response. You can only request groups granted on the API key. Defaults to the key's allowlist. A message payload can carry: call, customer, costs. Groups that belong to a completed conversation rather than a single message are omitted rather than returned empty.", "in": "query", "name": "fields", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated field groups to narrow the response. You can only request groups granted on the API key. Defaults to the key's allowlist. A message payload can carry: call, customer, costs. Groups that belong to a completed conversation rather than a single message are omitted rather than returned empty.", "title": "Fields" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageDetailResponseV1" } } }, "description": "Successful Response" }, "400": { "description": "Unknown name in `fields`" }, "401": { "description": "Missing, malformed, unknown, or revoked API key" }, "403": { "description": "The API key is not permitted to access the requested field groups" }, "404": { "description": "No such message in this workspace" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "503": { "description": "The partner API is disabled for this deployment" } }, "security": [ { "PartnerApiKey": [] } ], "summary": "Get message", "tags": [ "Messages" ] } }, "/v1/threads": { "get": { "description": "Completed conversations newest first, ordered on `completed_at`.\n\nEvery thread the webhook pushed is here under the same id, which is what\nmakes push the convenience and pull the guarantee.", "operationId": "list_workspace_threads_v1_threads_get", "parameters": [ { "description": "Cursor from a previous page", "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor from a previous page", "title": "Cursor" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Only conversations completed at or after this time (ISO 8601)", "in": "query", "name": "from", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Only conversations completed at or after this time (ISO 8601)", "title": "From" } }, { "description": "Only conversations completed at or before this time (ISO 8601)", "in": "query", "name": "to", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Only conversations completed at or before this time (ISO 8601)", "title": "To" } }, { "description": "Only conversations handled by this assistant", "in": "query", "name": "assistant_id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Only conversations handled by this assistant", "title": "Assistant Id" } }, { "description": "Restrict to one channel: sms, whatsapp", "in": "query", "name": "channel", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Restrict to one channel: sms, whatsapp", "title": "Channel" } }, { "description": "Restrict to one close reason, e.g. `graded`. Unrecognised values return an empty page rather than an error, because the vocabulary grows with the product.", "in": "query", "name": "close_reason", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Restrict to one close reason, e.g. `graded`. Unrecognised values return an empty page rather than an error, because the vocabulary grows with the product.", "title": "Close Reason" } }, { "description": "Comma-separated field groups to narrow the response. You can only request groups granted on the API key. Defaults to the key's allowlist. A thread payload can carry: call, customer, transcript, analysis, evaluations, costs, follow_ups. Recording, latency and configuration groups belong to a voice call and are omitted rather than returned empty.", "in": "query", "name": "fields", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated field groups to narrow the response. You can only request groups granted on the API key. Defaults to the key's allowlist. A thread payload can carry: call, customer, transcript, analysis, evaluations, costs, follow_ups. Recording, latency and configuration groups belong to a voice call and are omitted rather than returned empty.", "title": "Fields" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreadListResponseV1" } } }, "description": "Successful Response" }, "400": { "description": "Invalid cursor, unknown `fields` or `channel`" }, "401": { "description": "Missing, malformed, unknown, or revoked API key" }, "403": { "description": "The API key is not permitted to access the requested field groups" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "503": { "description": "The partner API is disabled for this deployment" } }, "security": [ { "PartnerApiKey": [] } ], "summary": "List threads", "tags": [ "Threads" ] } }, "/v1/threads/{thread_id}": { "get": { "description": "The same thread object the webhook delivers, fetched on demand.", "operationId": "get_workspace_thread_v1_threads__thread_id__get", "parameters": [ { "in": "path", "name": "thread_id", "required": true, "schema": { "format": "uuid", "title": "Thread Id", "type": "string" } }, { "description": "Comma-separated field groups to narrow the response. You can only request groups granted on the API key. Defaults to the key's allowlist. A thread payload can carry: call, customer, transcript, analysis, evaluations, costs, follow_ups. Recording, latency and configuration groups belong to a voice call and are omitted rather than returned empty.", "in": "query", "name": "fields", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated field groups to narrow the response. You can only request groups granted on the API key. Defaults to the key's allowlist. A thread payload can carry: call, customer, transcript, analysis, evaluations, costs, follow_ups. Recording, latency and configuration groups belong to a voice call and are omitted rather than returned empty.", "title": "Fields" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreadDetailResponseV1" } } }, "description": "Successful Response" }, "400": { "description": "Unknown name in `fields`" }, "401": { "description": "Missing, malformed, unknown, or revoked API key" }, "403": { "description": "The API key is not permitted to access the requested field groups" }, "404": { "description": "No such completed conversation in this workspace" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "503": { "description": "The partner API is disabled for this deployment" } }, "security": [ { "PartnerApiKey": [] } ], "summary": "Get thread", "tags": [ "Threads" ] } } }, "servers": [ { "description": "Production", "url": "https://api.voicetta.com" } ], "tags": [ { "description": "Agents in this workspace, with the numbers and variables a call needs.", "name": "Assistants" }, { "description": "Start a call, then read it back, including its recording.", "name": "Calls" }, { "description": "SMS and WhatsApp messages.", "name": "Messages" }, { "description": "Completed SMS and WhatsApp conversations.", "name": "Threads" }, { "description": "Events Voicetta POSTs to your server. Not routes you call.", "name": "Webhooks" } ], "webhooks": { "call.completed": { "post": { "description": "A voice call finished and was analysed. Voicetta POSTs this to the URL you registered. Respond with any 2xx to acknowledge. Anything else is retried.", "parameters": [ { "description": "HMAC of the timestamp and raw body. Verify this before trusting the payload.", "in": "header", "name": "X-Voicetta-Signature", "required": true, "schema": { "type": "string" } }, { "description": "Same value as the body's `event` field.", "in": "header", "name": "X-Voicetta-Event", "required": true, "schema": { "type": "string" } }, { "description": "Id of this delivery attempt. Retries of the same event reuse `event_id` in the body.", "in": "header", "name": "X-Voicetta-Delivery-Id", "required": true, "schema": { "type": "string" } }, { "description": "Payload version. Currently `1`.", "in": "header", "name": "X-Voicetta-Payload-Version", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallWebhookPayloadV1" } } }, "required": true }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery. The body is ignored." } }, "summary": "Call completed", "tags": [ "Webhooks" ] } }, "call.started": { "post": { "description": "An outbound call started dialling the destination. Sent before the call connects, so it carries no transcript or analysis. Voicetta POSTs this to the URL you registered. Respond with any 2xx to acknowledge. Anything else is retried.", "parameters": [ { "description": "HMAC of the timestamp and raw body. Verify this before trusting the payload.", "in": "header", "name": "X-Voicetta-Signature", "required": true, "schema": { "type": "string" } }, { "description": "Same value as the body's `event` field.", "in": "header", "name": "X-Voicetta-Event", "required": true, "schema": { "type": "string" } }, { "description": "Id of this delivery attempt. Retries of the same event reuse `event_id` in the body.", "in": "header", "name": "X-Voicetta-Delivery-Id", "required": true, "schema": { "type": "string" } }, { "description": "Payload version. Currently `1`.", "in": "header", "name": "X-Voicetta-Payload-Version", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallWebhookPayloadV1" } } }, "required": true }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery. The body is ignored." } }, "summary": "Call started", "tags": [ "Webhooks" ] } }, "message.received": { "post": { "description": "An SMS or WhatsApp message arrived, with the assistant's reply. Voicetta POSTs this to the URL you registered. Respond with any 2xx to acknowledge. Anything else is retried.", "parameters": [ { "description": "HMAC of the timestamp and raw body. Verify this before trusting the payload.", "in": "header", "name": "X-Voicetta-Signature", "required": true, "schema": { "type": "string" } }, { "description": "Same value as the body's `event` field.", "in": "header", "name": "X-Voicetta-Event", "required": true, "schema": { "type": "string" } }, { "description": "Id of this delivery attempt. Retries of the same event reuse `event_id` in the body.", "in": "header", "name": "X-Voicetta-Delivery-Id", "required": true, "schema": { "type": "string" } }, { "description": "Payload version. Currently `1`.", "in": "header", "name": "X-Voicetta-Payload-Version", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageWebhookPayloadV1" } } }, "required": true }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery. The body is ignored." } }, "summary": "Message received", "tags": [ "Webhooks" ] } }, "message.sent": { "post": { "description": "Voicetta sent an SMS or WhatsApp message on its own initiative. Voicetta POSTs this to the URL you registered. Respond with any 2xx to acknowledge. Anything else is retried.", "parameters": [ { "description": "HMAC of the timestamp and raw body. Verify this before trusting the payload.", "in": "header", "name": "X-Voicetta-Signature", "required": true, "schema": { "type": "string" } }, { "description": "Same value as the body's `event` field.", "in": "header", "name": "X-Voicetta-Event", "required": true, "schema": { "type": "string" } }, { "description": "Id of this delivery attempt. Retries of the same event reuse `event_id` in the body.", "in": "header", "name": "X-Voicetta-Delivery-Id", "required": true, "schema": { "type": "string" } }, { "description": "Payload version. Currently `1`.", "in": "header", "name": "X-Voicetta-Payload-Version", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageWebhookPayloadV1" } } }, "required": true }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery. The body is ignored." } }, "summary": "Message sent", "tags": [ "Webhooks" ] } }, "thread.completed": { "post": { "description": "An SMS or WhatsApp conversation finished and was graded. Voicetta POSTs this to the URL you registered. Respond with any 2xx to acknowledge. Anything else is retried.", "parameters": [ { "description": "HMAC of the timestamp and raw body. Verify this before trusting the payload.", "in": "header", "name": "X-Voicetta-Signature", "required": true, "schema": { "type": "string" } }, { "description": "Same value as the body's `event` field.", "in": "header", "name": "X-Voicetta-Event", "required": true, "schema": { "type": "string" } }, { "description": "Id of this delivery attempt. Retries of the same event reuse `event_id` in the body.", "in": "header", "name": "X-Voicetta-Delivery-Id", "required": true, "schema": { "type": "string" } }, { "description": "Payload version. Currently `1`.", "in": "header", "name": "X-Voicetta-Payload-Version", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreadWebhookPayloadV1" } } }, "required": true }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery. The body is ignored." } }, "summary": "Thread completed", "tags": [ "Webhooks" ] } } } }