{ "components": { "parameters": { "IdempotencyKey": { "description": "Run this request once; a retry with the same key and body gets the same answer.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } }, "responses": { "Error": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "400: The request is not valid; `error.field` names the part / 401: No key, or not a live one / 402: The account's prepaid credits are used up; top up in Texa Desk / 403: The key cannot do this (a sandbox route needs a test key) / 404: No such route, or nothing with that id in this account / 409: A conflict: the conversation's state, or an Idempotency-Key reused / 422: The body is not what this route takes / 429: Too many requests: wait `Retry-After` seconds / 503: Texa AI is not answering right now: retry after `Retry-After` seconds" } }, "schemas": { "Body_upload_media_v1_media_post": { "properties": { "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Conversation Id" }, "file": { "contentMediaType": "application/octet-stream", "description": "the bytes", "title": "File", "type": "string" }, "purpose": { "default": "message", "description": "message | research_answer", "title": "Purpose", "type": "string" } }, "required": [ "file" ], "title": "Body_upload_media_v1_media_post", "type": "object" }, "DocumentBody": { "properties": { "body": { "title": "Body", "type": "string" }, "kind": { "default": "other", "title": "Kind", "type": "string" }, "title": { "title": "Title", "type": "string" }, "uploaded_by": { "default": "", "title": "Uploaded By", "type": "string" } }, "required": [ "title", "body" ], "title": "DocumentBody", "type": "object" }, "Error": { "properties": { "error": { "properties": { "code": { "type": "string" }, "field": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "type": { "type": "string" } }, "type": "object" } }, "type": "object" }, "FixtureBody": { "additionalProperties": false, "properties": { "fault": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Fault" }, "response": { "additionalProperties": true, "title": "Response", "type": "object" }, "scenario": { "default": "default", "maxLength": 80, "title": "Scenario", "type": "string" } }, "required": [ "response" ], "title": "FixtureBody", "type": "object" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "title": "Detail", "type": "array" } }, "title": "HTTPValidationError", "type": "object" }, "HandbackBody": { "additionalProperties": false, "properties": { "by": { "default": "", "maxLength": 120, "title": "By", "type": "string" }, "note": { "default": "", "description": "what the person did and said, for Texa AI", "maxLength": 1000, "title": "Note", "type": "string" } }, "title": "HandbackBody", "type": "object" }, "HandoverBody": { "additionalProperties": false, "properties": { "reason": { "default": "", "maxLength": 200, "title": "Reason", "type": "string" }, "shadow": { "default": false, "description": "people answer by design and Texa AI drafts (/assist): kept out of every handover rate", "title": "Shadow", "type": "boolean" }, "taken_by": { "default": "", "maxLength": 120, "title": "Taken By", "type": "string" } }, "title": "HandoverBody", "type": "object" }, "HumanBody": { "additionalProperties": false, "properties": { "author": { "default": "", "maxLength": 120, "title": "Author", "type": "string" }, "message_id": { "anyOf": [ { "maxLength": 300, "type": "string" }, { "type": "null" } ], "title": "Message Id" }, "text": { "maxLength": 10000, "minLength": 1, "title": "Text", "type": "string" } }, "required": [ "text" ], "title": "HumanBody", "type": "object" }, "Me": { "properties": { "account": { "properties": { "country": { "type": "string" }, "currency": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "timezone": { "type": "string" } }, "type": "object" }, "environment": { "enum": [ "live", "test" ], "type": "string" }, "key": { "properties": { "hint": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "limits": { "properties": { "requests_per_minute": { "type": "integer" } }, "type": "object" } }, "type": "object" }, "MergeBody": { "additionalProperties": false, "properties": { "by": { "default": "", "maxLength": 120, "title": "By", "type": "string" }, "into": { "description": "the reference that stays", "maxLength": 200, "minLength": 1, "title": "Into", "type": "string" } }, "required": [ "into" ], "title": "MergeBody", "type": "object" }, "MessageBody": { "additionalProperties": false, "properties": { "attachments": { "description": "{media_id} from POST /v1/media - the turn waits for it to be understood; {type: location, latitude, longitude, name}; {type: contact, name, phone}; {type: sticker|reaction, emoji} - a mood, never a yes; or a description of a file", "items": { "additionalProperties": true, "type": "object" }, "maxItems": 20, "title": "Attachments", "type": "array" }, "headers": { "additionalProperties": true, "description": "email: Message-ID, In-Reply-To", "title": "Headers", "type": "object" }, "message_id": { "anyOf": [ { "maxLength": 300, "type": "string" }, { "type": "null" } ], "description": "your id for this message: a redelivery is answered, not re-run", "title": "Message Id" }, "reply_audio": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "from now on, replies also as voice notes (true) or not (false)", "title": "Reply Audio" }, "sender_name": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "title": "Sender Name" }, "sent_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Sent At" }, "subject": { "anyOf": [ { "maxLength": 300, "type": "string" }, { "type": "null" } ], "title": "Subject" }, "text": { "default": "", "maxLength": 50000, "title": "Text", "type": "string" } }, "title": "MessageBody", "type": "object" }, "OpenBody": { "additionalProperties": false, "properties": { "channel": { "enum": [ "whatsapp", "web", "sms", "instagram", "facebook", "telegram", "line", "tiktok", "email", "voice", "phone" ], "title": "Channel", "type": "string" }, "customer_ref": { "description": "your own reference for this customer", "maxLength": 200, "minLength": 1, "title": "Customer Ref", "type": "string" }, "first_name": { "anyOf": [ { "maxLength": 40, "type": "string" }, { "type": "null" } ], "title": "First Name" }, "known_facts": { "default": "", "description": "what your record says about them", "maxLength": 2000, "title": "Known Facts", "type": "string" }, "language": { "default": "en", "title": "Language", "type": "string" }, "objective": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "objective: e.g. checkin", "title": "Objective" }, "outbound": { "default": false, "description": "objective over a thread: the business writes first", "title": "Outbound", "type": "boolean" }, "procedure_set": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "support: which set", "title": "Procedure Set" }, "procedure_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "SANDBOX ONLY: run this version instead of the live one", "title": "Procedure Version" }, "purpose": { "default": "support", "enum": [ "support", "objective" ], "title": "Purpose", "type": "string" }, "reply_audio": { "default": false, "description": "each reply also carries `audio_media_id`: an OGG/Opus voice note of it", "title": "Reply Audio", "type": "boolean" }, "scenario": { "anyOf": [ { "maxLength": 80, "type": "string" }, { "type": "null" } ], "description": "SANDBOX: which fixtures answer actions", "title": "Scenario" }, "shadow": { "default": false, "description": "your shadow mode: people answer and Texa AI drafts (/assist); its handovers stay out of handover rates", "title": "Shadow", "type": "boolean" }, "subject": { "anyOf": [ { "maxLength": 300, "type": "string" }, { "type": "null" } ], "description": "email: the subject", "title": "Subject" } }, "required": [ "channel", "customer_ref" ], "title": "OpenBody", "type": "object" }, "ResultBody": { "additionalProperties": false, "properties": { "data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Data" }, "error": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Error" }, "request_id": { "title": "Request Id", "type": "string" }, "status": { "enum": [ "succeeded", "failed" ], "title": "Status", "type": "string" } }, "required": [ "request_id", "status" ], "title": "ResultBody", "type": "object" }, "Usage": { "properties": { "meters": { "items": { "properties": { "description": { "type": "string" }, "meter": { "type": "string" }, "quantity": { "type": "number" } }, "type": "object" }, "type": "array" }, "month": { "type": "string" } }, "type": "object" }, "ValidationError": { "properties": { "ctx": { "title": "Context", "type": "object" }, "input": { "title": "Input" }, "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" }, "VisitorSessionBody": { "properties": { "language": { "type": "string" }, "site_key": { "type": "string" } }, "required": [ "site_key" ], "type": "object" }, "VoiceSessionBody": { "additionalProperties": false, "properties": { "options": { "additionalProperties": true, "description": "mode (voice|text), brain, listens, speaks, voice, agent_name, agent_gender - chosen here, never by the app", "title": "Options", "type": "object" }, "ttl_s": { "default": 120, "maximum": 900.0, "minimum": 15.0, "title": "Ttl S", "type": "integer" } }, "title": "VoiceSessionBody", "type": "object" }, "WebhookEvent": { "properties": { "conversation_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "data": { "type": "object" }, "environment": { "enum": [ "live", "test" ], "type": "string" }, "id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type", "created_at", "environment", "data" ], "type": "object" }, "WidgetAnswer": { "properties": { "conversation_id": { "type": "string" }, "events": { "items": { "type": "object" }, "type": "array" }, "state": { "type": "string" } }, "type": "object" }, "WidgetAppResult": { "properties": { "data": { "type": "object" }, "error": { "type": "string" }, "request_id": { "type": "string" }, "status": { "enum": [ "succeeded", "failed" ], "type": "string" } }, "required": [ "request_id", "status" ], "type": "object" }, "WidgetDraft": { "properties": { "draft": { "type": "string" } }, "type": "object" }, "WidgetLines": { "properties": { "cards": { "items": { "properties": { "content": { "type": "string" }, "id": { "type": "integer" }, "kind": { "enum": [ "file", "sheet" ], "type": "string" }, "name": { "type": "string" }, "rows": { "type": "integer" }, "url": { "type": "string" } }, "type": "object" }, "type": "array" }, "changed": { "type": "string" }, "lines": { "items": { "properties": { "from": { "enum": [ "customer", "texa", "person" ], "type": "string" }, "n": { "type": "integer" }, "text": { "type": "string" } }, "type": "object" }, "type": "array" }, "preview": { "type": "boolean" }, "requests": { "items": { "properties": { "action": { "type": "string" }, "expires_at": { "type": [ "string", "null" ] }, "inputs": { "type": "object" }, "request_id": { "type": "string" } }, "type": "object" }, "type": "array" }, "with": { "type": [ "string", "null" ] } }, "type": "object" }, "WidgetMessage": { "properties": { "message_id": { "type": "string" }, "text": { "type": "string" } }, "required": [ "text" ], "type": "object" }, "WidgetMoved": { "properties": { "conversation_id": { "type": "string" }, "moved": { "type": "boolean" } }, "type": "object" }, "WidgetOpen": { "properties": { "channel": { "enum": [ "web", "voice" ], "type": "string" } }, "type": "object" }, "WidgetSession": { "properties": { "allowed_origins": { "items": { "type": "string" }, "type": "array" }, "customer_ref": { "type": "string" }, "environment": { "type": "string" }, "expires_at": { "type": "string" }, "signed_in": { "type": "boolean" }, "token": { "type": "string" } }, "type": "object" }, "WidgetSessionBody": { "properties": { "customer_ref": { "type": "string" }, "customer_token": { "description": "the customer's own token for your API, sent by a connector signed in with the signed-in customer's own token; sealed, never logged, never shown", "type": "string" }, "email": { "type": "string" }, "first_name": { "type": "string" }, "known_facts": { "type": "string" }, "language": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "ttl_s": { "maximum": 86400, "minimum": 60, "type": "integer" } }, "required": [ "customer_ref" ], "type": "object" }, "WidgetSignIn": { "properties": { "visitor_token": { "type": "string" } }, "required": [ "visitor_token" ], "type": "object" }, "WidgetVoice": { "properties": { "expires_at": { "type": "string" }, "token": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "api__v1__conversations__CloseBody": { "additionalProperties": false, "properties": { "reason": { "default": "closed_by_product", "maxLength": 80, "title": "Reason", "type": "string" } }, "title": "CloseBody", "type": "object" }, "api__v1__conversations__ForgetBody": { "additionalProperties": false, "properties": { "requested_by": { "maxLength": 120, "minLength": 2, "title": "Requested By", "type": "string" } }, "required": [ "requested_by" ], "title": "ForgetBody", "type": "object" } }, "securitySchemes": { "bearer": { "description": "texa_live_... or texa_test_...", "scheme": "bearer", "type": "http" }, "widgetSession": { "description": "wst_...: a widget session's token", "scheme": "bearer", "type": "http" } } }, "info": { "contact": { "email": "support@texa.ng", "name": "Texa support" }, "description": "Build Texa AI into your own software: open conversations from your app,\nwebsite or backend, send the customer's messages and get Texa AI's replies,\nrun actions in your systems, hand over to people, and hear about everything\nthrough webhooks.\n\n**Keys.** Every request carries `Authorization: Bearer `. Keys are made\nin Texa Desk, under Texa AI, Developers. A `texa_test_...` key reaches your\nsandbox (fixtures answer actions; nothing reaches a real customer); a\n`texa_live_...` key reaches your live account. Keep keys on your server:\nnever in an app or a web page.\n\n**Errors** are `{\"error\": {\"type\", \"code\", \"message\", \"field\"}}`, with the\nrequest's id in the `X-Request-Id` header. Quote it to Texa support.\n\n**Rate limits.** Each account has a limit per minute and environment\n(`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`). Over it,\nthe answer is 429 with `Retry-After`.\n\n**Idempotency.** Any POST may carry `Idempotency-Key`. The first request\nruns; a retry with the same key and the same body gets the same answer back,\nmarked `Idempotent-Replayed: true`; the same key with a different body is a\n409. Keys are kept for 24 hours. Messages also take your own `message_id`.\n\n**Actions.** When Texa AI needs something from your systems it asks with an\n`action_request` event. Actions you connected in Texa Desk run by themselves\nand come back marked `\"handled_by\": \"texa\"`; for the others, run the action\nand answer with `POST /v1/conversations/{id}/action-results`.\n\n**Events** are in the answer to each request, and every one of them is also\non `GET /v1/events` (in order, by cursor) and sent to your webhooks.\n\n**Webhooks** are signed: `X-Texa-Signature: sha256=.\">` with the endpoint's secret. Check it and\nthat the timestamp is recent, and use `X-Texa-Event-Id` to ignore repeats.\nFailed deliveries are retried for about a day.", "title": "Texa API", "version": "1" }, "openapi": "3.1.0", "paths": { "/v1/actions": { "get": { "description": "", "operationId": "list_actions", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "summary": "The actions Texa AI can ask for", "tags": [ "actions" ] } }, "/v1/actions/{name}": { "get": { "description": "", "operationId": "get_action", "parameters": [ { "in": "path", "name": "name", "required": true, "schema": { "title": "Name", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "summary": "One action", "tags": [ "actions" ] } }, "/v1/agent": { "get": { "description": "", "operationId": "get_agent", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "summary": "The agent your customers meet", "tags": [ "agent" ] } }, "/v1/conversations": { "get": { "description": "Newest first, by cursor. The cursor is the last conversation's id.", "operationId": "list_conversations", "parameters": [ { "in": "query", "name": "state", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "State" } }, { "in": "query", "name": "customer_ref", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Customer Ref" } }, { "description": "a cursor from `next`", "in": "query", "name": "after", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "a cursor from `next`", "title": "After" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "summary": "List conversations, newest first", "tags": [ "conversations" ] }, "post": { "description": "Connected actions in the answer run by themselves and are marked `\"handled_by\": \"texa\"`.\n\nTakes an `Idempotency-Key` header.", "operationId": "open_conversation", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenBody" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "summary": "Open a conversation", "tags": [ "conversations" ] } }, "/v1/conversations/{conversation_id}": { "get": { "description": "", "operationId": "get_conversation", "parameters": [ { "in": "path", "name": "conversation_id", "required": true, "schema": { "title": "Conversation Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "summary": "Get a conversation", "tags": [ "conversations" ] } }, "/v1/conversations/{conversation_id}/action-results": { "post": { "description": "Connected actions in the answer run by themselves and are marked `\"handled_by\": \"texa\"`.\n\nTakes an `Idempotency-Key` header.", "operationId": "post_action_result", "parameters": [ { "in": "path", "name": "conversation_id", "required": true, "schema": { "title": "Conversation Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResultBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "summary": "Give the result of an action you ran", "tags": [ "conversations" ] } }, "/v1/conversations/{conversation_id}/assist": { "post": { "description": "A suggested reply and action for the person holding it. Screened by the\nsame guards and gate, labelled `assist`, never sent or run by Texa AI.\n\nTakes an `Idempotency-Key` header.", "operationId": "assist", "parameters": [ { "in": "path", "name": "conversation_id", "required": true, "schema": { "title": "Conversation Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "summary": "A suggested reply for the person holding the conversation", "tags": [ "conversations" ] } }, "/v1/conversations/{conversation_id}/close": { "post": { "description": "Takes an `Idempotency-Key` header.", "operationId": "close_conversation", "parameters": [ { "in": "path", "name": "conversation_id", "required": true, "schema": { "title": "Conversation Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/api__v1__conversations__CloseBody" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "summary": "Close the conversation", "tags": [ "conversations" ] } }, "/v1/conversations/{conversation_id}/export": { "get": { "description": "Everything, in one read: the transcript, what was established and quoted,\nevery guard evaluation and - for a support conversation - every action\nstep, which is the audit answer to \"why did it do that\" (\u00a712).", "operationId": "export_conversation", "parameters": [ { "in": "path", "name": "conversation_id", "required": true, "schema": { "title": "Conversation Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "summary": "Everything about a conversation: transcript, actions, handovers", "tags": [ "records" ] } }, "/v1/conversations/{conversation_id}/handback": { "post": { "description": "Connected actions in the answer run by themselves and are marked `\"handled_by\": \"texa\"`.\n\nTakes an `Idempotency-Key` header.", "operationId": "hand_back", "parameters": [ { "in": "path", "name": "conversation_id", "required": true, "schema": { "title": "Conversation Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandbackBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "summary": "Hand the conversation back to Texa AI", "tags": [ "conversations" ] } }, "/v1/conversations/{conversation_id}/handover": { "post": { "description": "Takes an `Idempotency-Key` header.", "operationId": "hand_over", "parameters": [ { "in": "path", "name": "conversation_id", "required": true, "schema": { "title": "Conversation Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandoverBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "summary": "Hand the conversation to people", "tags": [ "conversations" ] } }, "/v1/conversations/{conversation_id}/human-messages": { "post": { "description": "Takes an `Idempotency-Key` header.", "operationId": "post_human_message", "parameters": [ { "in": "path", "name": "conversation_id", "required": true, "schema": { "title": "Conversation Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HumanBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "summary": "Record what a person said while they hold the conversation", "tags": [ "conversations" ] } }, "/v1/conversations/{conversation_id}/messages": { "post": { "description": "Connected actions in the answer run by themselves and are marked `\"handled_by\": \"texa\"`.\n\nTakes an `Idempotency-Key` header.", "operationId": "send_message", "parameters": [ { "in": "path", "name": "conversation_id", "required": true, "schema": { "title": "Conversation Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "summary": "Send the customer's message; the reply comes back in `events`", "tags": [ "conversations" ] } }, "/v1/conversations/{conversation_id}/quality": { "get": { "description": "", "operationId": "get_quality", "parameters": [ { "in": "path", "name": "conversation_id", "required": true, "schema": { "title": "Conversation Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "summary": "Quality scores", "tags": [ "records" ] } }, "/v1/conversations/{conversation_id}/transcript": { "get": { "description": "", "operationId": "get_transcript", "parameters": [ { "in": "path", "name": "conversation_id", "required": true, "schema": { "title": "Conversation Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "summary": "The transcript", "tags": [ "records" ] } }, "/v1/conversations/{conversation_id}/voice-sessions": { "post": { "description": "`url` is where your app opens the voice session, with the `token`, once, before `expires_at`. Never put a key in the app.\n\nTakes an `Idempotency-Key` header.", "operationId": "create_voice_session", "parameters": [ { "in": "path", "name": "conversation_id", "required": true, "schema": { "title": "Conversation Id", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceSessionBody" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "summary": "A single-use token for your app to open a voice session", "tags": [ "voice" ] } }, "/v1/customers/{customer_ref}": { "get": { "description": "What Texa AI remembers about one customer - each line with when and\nfrom which conversation - and their conversations with this account.", "operationId": "get_customer", "parameters": [ { "in": "path", "name": "customer_ref", "required": true, "schema": { "title": "Customer Ref", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "summary": "What Texa AI remembers about a customer", "tags": [ "customers" ] } }, "/v1/customers/{customer_ref}/forget": { "post": { "description": "Delete one customer: their memory, their conversations and their record\n(\u00a76.10, \u00a713). Cannot be undone; a row records that it happened.\n\nTakes an `Idempotency-Key` header.", "operationId": "forget_customer", "parameters": [ { "in": "path", "name": "customer_ref", "required": true, "schema": { "title": "Customer Ref", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api__v1__conversations__ForgetBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a customer's memory and conversations", "tags": [ "customers" ] } }, "/v1/customers/{customer_ref}/merge": { "post": { "description": "Two references, one person: `customer_ref`'s memory and conversations\nmove to `into`, and `customer_ref` is no more. Merging the same pair again\nanswers the first merge.\n\nTakes an `Idempotency-Key` header.", "operationId": "merge_customer", "parameters": [ { "in": "path", "name": "customer_ref", "required": true, "schema": { "title": "Customer Ref", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "summary": "Two references, one person: merge them", "tags": [ "customers" ] } }, "/v1/events": { "get": { "description": "", "operationId": "list_events", "parameters": [ { "description": "evt_", "in": "query", "name": "after", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "evt_", "title": "After" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 1000, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "comma separated", "in": "query", "name": "types", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "comma separated", "title": "Types" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "summary": "Every event, in order, after a cursor", "tags": [ "events" ] } }, "/v1/kill-switch": { "get": { "description": "", "operationId": "get_kill_switch", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "summary": "Whether Texa AI is paused", "tags": [ "agent" ] } }, "/v1/knowledge/documents": { "get": { "description": "", "operationId": "list_documents", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "summary": "Knowledge documents and their approval", "tags": [ "knowledge" ] }, "post": { "description": "Takes an `Idempotency-Key` header.", "operationId": "add_document", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentBody" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "summary": "Add a document; it is used once a person approves it in Texa Desk", "tags": [ "knowledge" ] } }, "/v1/me": { "get": { "description": "The account and key this request uses, and its rate limit.", "operationId": "get_me", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "summary": "The account and key this request uses", "tags": [ "account" ] } }, "/v1/media": { "post": { "description": "Sizes: audio 16 MB, image 10 MB, document 20 MB, video 64 MB (settings\nmedia.max_mb_*). A voice note is heard up to 3 minutes (media.audio_max_s).\n\nTakes an `Idempotency-Key` header.", "operationId": "upload_media", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_upload_media_v1_media_post" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "summary": "Upload a voice note, photo, document or video", "tags": [ "media" ] } }, "/v1/media/{media_id}": { "get": { "description": "", "operationId": "get_media", "parameters": [ { "in": "path", "name": "media_id", "required": true, "schema": { "title": "Media Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "summary": "A media item and what was understood from it", "tags": [ "media" ] } }, "/v1/media/{media_id}/content": { "get": { "description": "", "operationId": "get_media_content", "parameters": [ { "in": "path", "name": "media_id", "required": true, "schema": { "title": "Media Id", "type": "string" } } ], "responses": { "200": { "content": { "audio/ogg": {} }, "description": "Successful Response" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "summary": "The media item's bytes", "tags": [ "media" ] } }, "/v1/reports/quality": { "get": { "description": "", "operationId": "get_quality_report", "parameters": [ { "in": "query", "name": "since", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Since" } }, { "in": "query", "name": "until", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Until" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "summary": "Quality report", "tags": [ "reports" ] } }, "/v1/reports/support": { "get": { "description": "", "operationId": "get_support_report", "parameters": [ { "in": "query", "name": "since", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Since" } }, { "in": "query", "name": "until", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Until" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "summary": "Support report", "tags": [ "reports" ] } }, "/v1/sandbox/actions": { "get": { "description": "Sandbox only: use a test key (`texa_test_...`).", "operationId": "list_fixtures", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "summary": "Sandbox fixtures", "tags": [ "sandbox" ] } }, "/v1/sandbox/actions/{action}": { "delete": { "description": "Sandbox only: use a test key (`texa_test_...`).", "operationId": "delete_fixture", "parameters": [ { "in": "path", "name": "action", "required": true, "schema": { "title": "Action", "type": "string" } }, { "in": "query", "name": "scenario", "required": false, "schema": { "default": "default", "title": "Scenario", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "summary": "Remove a sandbox fixture", "tags": [ "sandbox" ] }, "put": { "description": "Sandbox only: use a test key (`texa_test_...`).", "operationId": "put_fixture", "parameters": [ { "in": "path", "name": "action", "required": true, "schema": { "title": "Action", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FixtureBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "summary": "Set what an action answers in the sandbox", "tags": [ "sandbox" ] } }, "/v1/usage": { "get": { "description": "What has been counted this month, per meter: what draws down the account's credits. Test-key requests are counted as `sandbox_requests`.", "operationId": "get_usage", "parameters": [ { "description": "YYYY-MM; this month when left out", "in": "query", "name": "month", "required": false, "schema": { "pattern": "^\\d{4}-\\d{2}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "summary": "Usage this month, per meter", "tags": [ "account" ] } }, "/v1/widget-sessions": { "post": { "description": "A session for one of your customers, for a widget in a web page or an app. Give its `token` to the page or app: it reaches only the `/v1/widget/...` routes, for this customer, until `expires_at`. Make it on your server; never put a key in the page.\n\nTakes an `Idempotency-Key` header.", "operationId": "create_widget_session", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetSessionBody" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetSession" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "summary": "A widget session for one customer: its token is for a web page or an app", "tags": [ "widgets" ] } }, "/v1/widget/conversations": { "post": { "description": "Opens a conversation for the session's customer.", "operationId": "widget_open_conversation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetOpen" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetAnswer" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "widgetSession": [] } ], "summary": "Open the session customer's conversation (web or voice)", "tags": [ "widgets" ] } }, "/v1/widget/conversations/{conversation_id}/app-results": { "post": { "description": "Your page or app ran a screen action Texa AI asked for (from `requests` on the lines): its outputs, or why it failed. Within 30 seconds; once. The answer is what Texa AI says next.", "operationId": "widget_app_result", "parameters": [ { "in": "path", "name": "conversation_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetAppResult" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetAnswer" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "widgetSession": [] } ], "summary": "A screen action's answer, from the customer's page or app", "tags": [ "widgets" ] } }, "/v1/widget/conversations/{conversation_id}/cards/{card_id}/content": { "get": { "description": "A spreadsheet Texa AI sent the customer (a card of kind `sheet`), as CSV.", "operationId": "widget_card_content", "parameters": [ { "in": "path", "name": "conversation_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "card_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "text/csv": {} }, "description": "The CSV" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "widgetSession": [] } ], "summary": "A spreadsheet Texa AI sent the customer, as CSV", "tags": [ "widgets" ] } }, "/v1/widget/conversations/{conversation_id}/files": { "post": { "description": "A photo, PDF, Word document, recording or short video from the customer (multipart: `file`, and optional `text` and `message_id`), 10 MB at most, checked by its first bytes.", "operationId": "widget_send_file", "parameters": [ { "in": "path", "name": "conversation_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "properties": { "file": { "format": "binary", "type": "string" }, "message_id": { "type": "string" }, "text": { "type": "string" } }, "required": [ "file" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetAnswer" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "widgetSession": [] } ], "summary": "A photo, PDF or recording from the customer", "tags": [ "widgets" ] } }, "/v1/widget/conversations/{conversation_id}/lines": { "get": { "description": "What was said after line `after`: replies that came later and people's answers; documents Texa AI sent after card `after_card`; screen actions this page should run now (`requests`). Poll it every few seconds while the chat is open. Pass the last `changed` as `seen`: a poll with nothing new is then cheap; `fresh=1` reads everything (after a send, and every few polls).", "operationId": "widget_lines", "parameters": [ { "in": "query", "name": "after", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "after_card", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "seen", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "fresh", "required": false, "schema": { "type": "boolean" } }, { "in": "path", "name": "conversation_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetLines" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "widgetSession": [] } ], "summary": "What was said since a line: late replies, people's answers", "tags": [ "widgets" ] } }, "/v1/widget/conversations/{conversation_id}/messages": { "post": { "description": "The customer's message. The answer shows only what a customer may see: replies, a handover, a close.", "operationId": "widget_send_message", "parameters": [ { "in": "path", "name": "conversation_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetMessage" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetAnswer" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "widgetSession": [] } ], "summary": "The customer's message, from the widget", "tags": [ "widgets" ] } }, "/v1/widget/conversations/{conversation_id}/sign-in": { "post": { "description": "Call with the session your server made once the visitor signed in, and the visitor's token: the chat carries on as the customer. `moved` says whether it carries on in a new conversation.", "operationId": "widget_sign_in", "parameters": [ { "in": "path", "name": "conversation_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetSignIn" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetMoved" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "widgetSession": [] } ], "summary": "The visitor signed in: the chat carries on as the customer", "tags": [ "widgets" ] } }, "/v1/widget/conversations/{conversation_id}/typing": { "post": { "description": "What the customer is typing, for the people who see the chat in Texa Desk: mask it first (digits and anything after pin, otp, code or password, as the guide shows), at most one every 300 ms; an empty `draft` clears it. Never stored or logged.", "operationId": "widget_typing", "parameters": [ { "in": "path", "name": "conversation_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetDraft" } } }, "required": true }, "responses": { "204": { "description": "Taken" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "widgetSession": [] } ], "summary": "What the customer is typing, masked, for the team", "tags": [ "widgets" ] } }, "/v1/widget/conversations/{conversation_id}/voice-sessions": { "post": { "description": "A single-use token for the widget's voice line (a voice conversation).", "operationId": "widget_voice_session", "parameters": [ { "in": "path", "name": "conversation_id", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetVoice" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "widgetSession": [] } ], "summary": "A single-use token for the widget's voice line", "tags": [ "widgets" ] } }, "/v1/widget/visitor-sessions": { "post": { "description": "A session for a visitor who hasn't signed in, from the account's site key (Texa Desk, Developers, Website and app). Live, only from the account's allowed websites; 20 an hour per address. A visitor is never verified, and actions kept for signed-in customers are refused for them.", "operationId": "widget_visitor_session", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisitorSessionBody" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetSession" } } }, "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "A signed-out visitor's session, from the account's site key", "tags": [ "widgets" ] } } }, "security": [ { "bearer": [] } ], "servers": [ { "url": "https://api.texadesk.com" } ], "tags": [ { "name": "conversations" }, { "name": "voice" }, { "name": "records" }, { "name": "customers" }, { "name": "events" }, { "name": "media" }, { "name": "agent" }, { "name": "actions" }, { "name": "knowledge" }, { "name": "reports" }, { "name": "sandbox" }, { "name": "widgets" }, { "name": "account" } ], "webhooks": { "call.ended": { "post": { "description": "A call ended. Signed: check `X-Texa-Signature` before trusting it.", "operationId": "webhook_call_ended", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx within 10 seconds is delivered; anything else is retried." } }, "summary": "A call ended" } }, "call.started": { "post": { "description": "A call started. Signed: check `X-Texa-Signature` before trusting it.", "operationId": "webhook_call_started", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx within 10 seconds is delivered; anything else is retried." } }, "summary": "A call started" } }, "conversation.action_request": { "post": { "description": "Texa AI asked for an action to be run. Signed: check `X-Texa-Signature` before trusting it.", "operationId": "webhook_conversation_action_request", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx within 10 seconds is delivered; anything else is retried." } }, "summary": "Texa AI asked for an action to be run" } }, "conversation.closed": { "post": { "description": "The conversation was closed. Signed: check `X-Texa-Signature` before trusting it.", "operationId": "webhook_conversation_closed", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx within 10 seconds is delivered; anything else is retried." } }, "summary": "The conversation was closed" } }, "conversation.handback": { "post": { "description": "People handed the conversation back to Texa AI. Signed: check `X-Texa-Signature` before trusting it.", "operationId": "webhook_conversation_handback", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx within 10 seconds is delivered; anything else is retried." } }, "summary": "People handed the conversation back to Texa AI" } }, "conversation.handover": { "post": { "description": "Texa AI handed the conversation to people. Signed: check `X-Texa-Signature` before trusting it.", "operationId": "webhook_conversation_handover", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx within 10 seconds is delivered; anything else is retried." } }, "summary": "Texa AI handed the conversation to people" } }, "conversation.human_message": { "post": { "description": "A person answered the customer from Texa Desk (headless handover): show it in your app. Signed: check `X-Texa-Signature` before trusting it.", "operationId": "webhook_conversation_human_message", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx within 10 seconds is delivered; anything else is retried." } }, "summary": "A person answered the customer from Texa Desk (headless handover): show it in your app" } }, "conversation.opened": { "post": { "description": "A conversation was opened. Signed: check `X-Texa-Signature` before trusting it.", "operationId": "webhook_conversation_opened", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx within 10 seconds is delivered; anything else is retried." } }, "summary": "A conversation was opened" } }, "conversation.reply": { "post": { "description": "Texa AI replied to the customer. Signed: check `X-Texa-Signature` before trusting it.", "operationId": "webhook_conversation_reply", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx within 10 seconds is delivered; anything else is retried." } }, "summary": "Texa AI replied to the customer" } }, "interview.completed": { "post": { "description": "A research interview was completed. Signed: check `X-Texa-Signature` before trusting it.", "operationId": "webhook_interview_completed", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx within 10 seconds is delivered; anything else is retried." } }, "summary": "A research interview was completed" } }, "media.failed": { "post": { "description": "A media item could not be understood. Signed: check `X-Texa-Signature` before trusting it.", "operationId": "webhook_media_failed", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx within 10 seconds is delivered; anything else is retried." } }, "summary": "A media item could not be understood" } }, "media.understood": { "post": { "description": "A voice note, photo, document or video was understood. Signed: check `X-Texa-Signature` before trusting it.", "operationId": "webhook_media_understood", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx within 10 seconds is delivered; anything else is retried." } }, "summary": "A voice note, photo, document or video was understood" } }, "monitor.finding": { "post": { "description": "A monitor found something in a conversation. Signed: check `X-Texa-Signature` before trusting it.", "operationId": "webhook_monitor_finding", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx within 10 seconds is delivered; anything else is retried." } }, "summary": "A monitor found something in a conversation" } }, "quality.scored": { "post": { "description": "A closed conversation was scored. Signed: check `X-Texa-Signature` before trusting it.", "operationId": "webhook_quality_scored", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx within 10 seconds is delivered; anything else is retried." } }, "summary": "A closed conversation was scored" } }, "report.ready": { "post": { "description": "A report is ready. Signed: check `X-Texa-Signature` before trusting it.", "operationId": "webhook_report_ready", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx within 10 seconds is delivered; anything else is retried." } }, "summary": "A report is ready" } }, "survey.response": { "post": { "description": "A customer completed a survey. Signed: check `X-Texa-Signature` before trusting it.", "operationId": "webhook_survey_response", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx within 10 seconds is delivered; anything else is retried." } }, "summary": "A customer completed a survey" } } } }