{ "openapi": "3.1.0", "info": { "title": "Shortext API", "description": "**Versioning**: every version is a frozen contract. A released version only receives additive changes\n(new endpoints, new optional fields, new response fields); anything breaking ships in a new version.\nResponses carry `X-Shortext-Api-Version`. When a version is scheduled for removal, responses also carry\n`Deprecation` and `Sunset` headers; after the sunset date the version answers HTTP 410.\nThe list of versions and their status is available at `GET /api/versions`.\n\n**Responses**: always HTTP 200. Check `success` and `code` (`1000` = success), see `ApiEnvelope`.\nOn failure, `trace_id` identifies the request for support.\n\n**Rate limit**: 300 requests per minute per company, shared by all its keys and by every API version.\nResponses carry `X-RateLimit-Limit` and `X-RateLimit-Remaining`; beyond the limit the API answers\nHTTP 429 with `Retry-After` (seconds) and the usual envelope. Prefer webhooks to polling.", "version": "2.0" }, "servers": [ { "url": "https://shortext.ny-corp.io/api/v2.0" } ], "paths": { "/agents": { "get": { "tags": [ "Agents" ], "summary": "List agents", "description": "Most recent first, 50 per page. Filter with `name`, `active`, `use_ai`.", "operationId": "listAgents", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "allOf": [ { "$ref": "#/components/schemas/ApiPage" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } } }, "type": "object" } ] } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Agents" ], "summary": "Create an agent", "description": "Refused once the plan agent limit is reached. Attach channels with `PUT /channels/{type}/{id}/agent`.", "operationId": "createAgent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentInput" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/Agent" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{id}": { "get": { "tags": [ "Agents" ], "summary": "Get an agent", "operationId": "getAgent", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "AGI-XXXXX" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/Agent" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Agents" ], "summary": "Delete an agent", "description": "Refused while the agent still has channels: move or detach them first, or set `active` to false instead. Tickets, commands and tools are kept and the agent can be restored.", "operationId": "deleteAgent", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The deleted Agent", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/Agent" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "tags": [ "Agents" ], "summary": "Update an agent", "description": "Partial update: only the fields sent change (PUT is accepted too).", "operationId": "updateAgent", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentInput" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/Agent" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{id}/restore": { "patch": { "tags": [ "Agents" ], "summary": "Restore a deleted agent", "description": "Refused when the plan agent limit is reached.", "operationId": "restoreAgent", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/Agent" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{agent}/knowledge": { "get": { "tags": [ "Knowledge" ], "summary": "List knowledge documents", "description": "Most recent first, 50 per page, without the full content. Search the titles and contents with `search`.", "operationId": "listKnowledgeDocuments", "parameters": [ { "name": "agent", "in": "path", "required": true, "schema": { "type": "string", "example": "AGI-XXXXX" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "allOf": [ { "$ref": "#/components/schemas/ApiPage" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeDocument" } } }, "type": "object" } ] } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Knowledge" ], "summary": "Add a knowledge document", "description": "Send `title` and `content` (Markdown) as JSON, or upload a PDF as multipart/form-data. Refused beyond the characters of the plan (`GET /agents/{agent}/knowledge/usage`). The AI uses the document at once.", "operationId": "createKnowledgeDocument", "parameters": [ { "name": "agent", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/KnowledgeDocumentInput" } }, "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeDocumentInput" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/KnowledgeDocument" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{agent}/knowledge/{id}": { "get": { "tags": [ "Knowledge" ], "summary": "Get a knowledge document", "operationId": "getKnowledgeDocument", "parameters": [ { "name": "agent", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "KNB-XXXXX" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/KnowledgeDocument" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Knowledge" ], "summary": "Delete a knowledge document", "description": "The AI stops using it at once.", "operationId": "deleteKnowledgeDocument", "parameters": [ { "name": "agent", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The deleted KnowledgeDocument", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/KnowledgeDocument" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "tags": [ "Knowledge" ], "summary": "Update a knowledge document", "description": "Partial update (PUT is accepted too); the AI uses the new content at once.", "operationId": "updateKnowledgeDocument", "parameters": [ { "name": "agent", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeDocumentInput" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/KnowledgeDocument" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{agent}/knowledge/usage": { "get": { "tags": [ "Knowledge" ], "summary": "Knowledge base usage", "operationId": "getKnowledgeUsage", "parameters": [ { "name": "agent", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/KnowledgeUsage" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/deep-links/platforms": { "get": { "tags": [ "Dynamic links" ], "summary": "List apps", "description": "Filter with `agent_id` and `platform`.", "operationId": "listAppPlatforms", "parameters": [ { "name": "agent_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "android", "ios" ] } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "allOf": [ { "$ref": "#/components/schemas/ApiPage" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AppPlatform" } } }, "type": "object" } ] } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Dynamic links" ], "summary": "Add an app", "operationId": "createAppPlatform", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppPlatformInput" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/AppPlatform" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/deep-links/platforms/{id}": { "get": { "tags": [ "Dynamic links" ], "summary": "Get an app", "operationId": "getAppPlatform", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/AppPlatform" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Dynamic links" ], "summary": "Delete an app", "description": "Refused while dynamic links open this app.", "operationId": "deleteAppPlatform", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The deleted AppPlatform", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/AppPlatform" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "tags": [ "Dynamic links" ], "summary": "Update an app", "description": "Partial update (PUT is accepted too); the platform cannot change.", "operationId": "updateAppPlatform", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppPlatformInput" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/AppPlatform" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/deep-links/platforms/{id}/verification-file": { "get": { "tags": [ "Dynamic links" ], "summary": "Domain verification file", "description": "Serve `content` as JSON at `https:///.well-known/` so the phone opens the links in the app.", "operationId": "getAppPlatformVerificationFile", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "allOf": [ { "properties": { "filename": { "type": "string", "enum": [ "assetlinks.json", "apple-app-site-association" ] }, "content": { "type": "object" } }, "type": "object" } ] } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/balance": { "get": { "tags": [ "Billing" ], "summary": "Company balance", "operationId": "getBalance", "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/Balance" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/balance/transactions": { "get": { "tags": [ "Billing" ], "summary": "Wallet movements", "description": "Settled movements, most recent first, 50 per page. A debit appears once it is settled.", "operationId": "listBalanceTransactions", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "type", "in": "query", "description": "`debit` or `credit`", "required": false, "schema": { "type": "string", "enum": [ "debit", "credit" ] } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "allOf": [ { "$ref": "#/components/schemas/ApiPage" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BalanceTransaction" } } }, "type": "object" } ] } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/campaigns": { "get": { "tags": [ "Campaigns" ], "summary": "List campaigns", "description": "Most recent first, 50 per page. Filter with `status` and `name`.", "operationId": "listCampaigns", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "scheduled", "active", "paused", "ended", "failed" ] } }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "allOf": [ { "$ref": "#/components/schemas/ApiPage" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Campaign" } } }, "type": "object" } ] } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Campaigns" ], "summary": "Create a campaign", "description": "Created as a draft: check it (`GET /campaigns/{id}/checks`) and launch it (`POST /campaigns/{id}/launch`).", "operationId": "createCampaign", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignInput" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/Campaign" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/campaigns/{id}": { "get": { "tags": [ "Campaigns" ], "summary": "Get a campaign", "operationId": "getCampaign", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "CMP-XXXXX" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/Campaign" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Campaigns" ], "summary": "Delete a campaign", "description": "Only a campaign that never sent anything (a draft, a failed one). Pause a running campaign instead.", "operationId": "deleteCampaign", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The deleted Campaign", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/Campaign" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "tags": [ "Campaigns" ], "summary": "Update a campaign", "description": "Partial update (PUT is accepted too) of a draft, failed or paused campaign.", "operationId": "updateCampaign", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignInput" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/Campaign" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/campaigns/{id}/checks": { "get": { "tags": [ "Campaigns" ], "summary": "Launch checks of a campaign", "description": "What must be true before the campaign goes out; a `block` check stops the launch.", "operationId": "checkCampaign", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignCheck" } } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/campaigns/{id}/estimate": { "get": { "tags": [ "Campaigns" ], "summary": "Estimated cost of a campaign", "description": "Reachable recipients per channel times the price of one message: its category (the template's on WhatsApp) and the recipient's country.", "operationId": "estimateCampaign", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/CampaignEstimate" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/campaigns/{id}/launch": { "post": { "tags": [ "Campaigns" ], "summary": "Launch a campaign", "description": "Sends the campaign now, or at `start_at` when it is in the future. Refused with the blocking checks when one blocks. An automatic campaign becomes active and sends on each new conversation.", "operationId": "launchCampaign", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "start_at": { "type": [ "string", "null" ], "format": "date-time" } }, "type": "object" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/Campaign" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/campaigns/{id}/pause": { "post": { "tags": [ "Campaigns" ], "summary": "Pause a campaign", "description": "The messages not sent yet wait; a start not reached yet is cancelled.", "operationId": "pauseCampaign", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/Campaign" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/campaigns/{id}/resume": { "post": { "tags": [ "Campaigns" ], "summary": "Resume a paused campaign", "description": "Sends the messages left waiting (within the send window).", "operationId": "resumeCampaign", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/Campaign" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/campaigns/{id}/duplicate": { "post": { "tags": [ "Campaigns" ], "summary": "Duplicate a campaign", "description": "A draft copy with the same settings, channels and messages, without audience (a segment is kept), dates or statistics.", "operationId": "duplicateCampaign", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The new draft", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/Campaign" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/campaigns/{id}/report": { "get": { "tags": [ "Campaigns" ], "summary": "Report of a campaign", "description": "Counts, rates and delays of the campaign, per channel too, and its cost so far. Refreshed every few minutes.", "operationId": "getCampaignReport", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/CampaignReport" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/campaigns/{id}/recipients": { "get": { "tags": [ "Campaigns" ], "summary": "Recipients of a campaign", "description": "One row per contact and channel, 50 per page. `filter`: all, read_no_reply, replied, unread or failed.", "operationId": "listCampaignRecipients", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "filter", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "read_no_reply", "replied", "unread", "failed" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "allOf": [ { "$ref": "#/components/schemas/ApiPage" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignRecipient" } } }, "type": "object" } ] } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/campaign-imports": { "post": { "tags": [ "Campaigns" ], "summary": "Upload a contact file", "description": "A .xlsx or .csv file (multipart, field `file`) with a phone number column. The columns are guessed from their headers; numbers without a country code get the company's.", "operationId": "uploadCampaignImport", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "properties": { "file": { "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/CampaignImport" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/campaign-imports/{id}": { "get": { "tags": [ "Campaigns" ], "summary": "Get a contact file", "description": "Its columns and, once checked, its report.", "operationId": "getCampaignImport", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "IMP-XXXXX" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/CampaignImport" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "tags": [ "Campaigns" ], "summary": "Map the columns of a contact file", "description": "What each column holds, by index: `phone` (one column, required), `first_name`, `last_name`, `email`, `var:` or `ignore`.", "operationId": "mapCampaignImport", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "columns": { "type": "object", "example": [ "phone", "first_name", "var:amount" ] }, "has_header": { "type": "boolean", "default": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/CampaignImport" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/campaign-imports/{id}/check": { "post": { "tags": [ "Campaigns" ], "summary": "Check a contact file", "description": "Counts valid numbers, merged duplicates, invalid numbers (with their row), unsubscribed contacts and new contacts. A large file is checked in the background: GET it until its status is `checked`.", "operationId": "checkCampaignImport", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "marketing": { "description": "Count unsubscribed contacts out (they get no marketing campaign)", "type": "boolean", "default": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/CampaignImport" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/campaign-segments": { "get": { "tags": [ "Campaigns" ], "summary": "List segments", "description": "50 per page.", "operationId": "listCampaignSegments", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "allOf": [ { "$ref": "#/components/schemas/ApiPage" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignSegment" } } }, "type": "object" } ] } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/campaign-segments/{id}": { "get": { "tags": [ "Campaigns" ], "summary": "Get a segment", "operationId": "getCampaignSegment", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "SEG-XXXXX" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/CampaignSegment" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/channels": { "get": { "tags": [ "Channels" ], "summary": "List channels", "description": "Every WhatsApp number, mailbox, Shortext endpoint and Telegram bot of the company, with the agent answering on it.", "operationId": "listChannels", "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "whatsapp", "mail", "shortext", "telegram" ] } }, { "name": "agent_id", "in": "query", "description": "Only the channels of this agent; \"none\" for detached channels", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "type": "array", "items": { "$ref": "#/components/schemas/Channel" } } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/channels/{type}/{id}": { "get": { "tags": [ "Channels" ], "summary": "Get a channel", "operationId": "getChannel", "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "whatsapp", "mail", "shortext", "telegram" ] } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/Channel" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/channels/{type}/{id}/agent": { "put": { "tags": [ "Channels" ], "summary": "Attach or move a channel", "description": "Attaches the channel to the agent, or moves it from its current agent. The agent answers the next messages.", "operationId": "attachChannelAgent", "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "whatsapp", "mail", "shortext", "telegram" ] } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "agent_id" ], "properties": { "agent_id": { "type": "string", "example": "AGI-XXXXX" } }, "type": "object" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/Channel" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Channels" ], "summary": "Detach a channel from its agent", "description": "The channel keeps receiving and storing messages, nobody answers automatically until an agent is attached again.", "operationId": "detachChannelAgent", "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "whatsapp", "mail", "shortext", "telegram" ] } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/Channel" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{agent}/contact-knowledge": { "get": { "tags": [ "Knowledge" ], "summary": "List contact knowledge", "description": "Most recent first, 50 per page.", "operationId": "listContactKnowledge", "parameters": [ { "name": "agent", "in": "path", "required": true, "schema": { "type": "string", "example": "AGI-XXXXX" } }, { "name": "contact", "in": "query", "description": "Only about this contact: phone number, email address or, on a Shortext endpoint, the id your server gave", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "allOf": [ { "$ref": "#/components/schemas/ApiPage" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContactKnowledge" } } }, "type": "object" } ] } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Knowledge" ], "summary": "Add contact knowledge", "description": "The contact must have written to the company. The AI uses it from the next message of this contact.", "operationId": "createContactKnowledge", "parameters": [ { "name": "agent", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "contact", "content" ], "properties": { "contact": { "description": "Phone number, email address or, on a Shortext endpoint, the id your server gave", "type": "string" }, "content": { "type": "string", "maxLength": 5000, "example": "Prefers to be called Mrs. Ndongo; VIP customer since 2023." } }, "type": "object" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/ContactKnowledge" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{agent}/contact-knowledge/{id}": { "get": { "tags": [ "Knowledge" ], "summary": "Get a contact knowledge entry", "operationId": "getContactKnowledge", "parameters": [ { "name": "agent", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "MEM-XXXXX" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/ContactKnowledge" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Knowledge" ], "summary": "Delete contact knowledge", "description": "The AI stops using it at once.", "operationId": "deleteContactKnowledge", "parameters": [ { "name": "agent", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The deleted ContactKnowledge", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/ContactKnowledge" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "tags": [ "Knowledge" ], "summary": "Update contact knowledge", "description": "PUT is accepted too.", "operationId": "updateContactKnowledge", "parameters": [ { "name": "agent", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "content" ], "properties": { "content": { "type": "string", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/ContactKnowledge" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/conversations": { "get": { "tags": [ "Conversations" ], "summary": "List conversations", "description": "Most recent message first, 50 per page.", "operationId": "listConversations", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "archived" ] } }, { "name": "agent_id", "in": "query", "description": "Conversations of this agent's channels; \"none\" for detached channels", "required": false, "schema": { "type": "string" } }, { "name": "channel", "in": "query", "description": "Channel type", "required": false, "schema": { "type": "string", "enum": [ "whatsapp", "mail", "shortext", "telegram" ] } }, { "name": "channel_id", "in": "query", "description": "With `channel`: one channel (the channel_id of the webhooks)", "required": false, "schema": { "type": "string" } }, { "name": "contact", "in": "query", "description": "Contact identifier (phone, email, or your own id for Shortext)", "required": false, "schema": { "type": "string" } }, { "name": "assignee", "in": "query", "description": "\"me\" (user tokens only), \"none\", or a member id (GET /conversations/assignees)", "required": false, "schema": { "type": "string" } }, { "name": "ticket_id", "in": "query", "description": "The conversation of a ticket (ticket reference)", "required": false, "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "description": "Last message at or after this date", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "allOf": [ { "$ref": "#/components/schemas/ApiPage" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" } } }, "type": "object" } ] } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Conversations" ], "summary": "Start a conversation", "description": "Sends a first message to a contact from one of your channels, and opens the conversation (or continues the existing one). On WhatsApp, outside the 24h window opened by the contact, only an approved template can be sent (GET /templates). The AI agent keeps answering the contact unless `handover` is true.", "operationId": "startConversation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartConversationInput" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "properties": { "conversation": { "$ref": "#/components/schemas/Conversation" }, "message": { "$ref": "#/components/schemas/Message" } }, "type": "object" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/conversations/{id}": { "get": { "tags": [ "Conversations" ], "summary": "Get a conversation", "operationId": "getConversation", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/Conversation" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/conversations/{id}/messages": { "get": { "tags": [ "Conversations" ], "summary": "List the messages of a conversation", "description": "Most recent first, 50 per page. Same data as the message.* webhooks.", "operationId": "listConversationMessages", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "allOf": [ { "$ref": "#/components/schemas/ApiPage" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } }, "type": "object" } ] } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Conversations" ], "summary": "Reply to a conversation", "description": "Same message grammar as every endpoint (text, template, interactive, media). Out of the WhatsApp 24h window a free-form message is sent as a notification template. By default the reply takes the conversation over (`handover`): the AI agent stops answering, as when a human answers in the Inbox. A user token of an agent (role) cannot answer a conversation assigned to someone else.", "operationId": "replyToConversation", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplyInput" } } } }, "responses": { "200": { "description": "The sent Message", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/Message" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/conversations/{id}/handover": { "put": { "tags": [ "Conversations" ], "summary": "Take a conversation over", "description": "A human takes the conversation over: the AI agent stops answering (webhook conversation.handover). Needs an active session.", "operationId": "handoverConversation", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/Conversation" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Conversations" ], "summary": "Hand a conversation back to the agent", "description": "The AI agent answers again (webhook conversation.released).", "operationId": "releaseConversation", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/Conversation" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/conversations/{id}/assignee": { "put": { "tags": [ "Conversations" ], "summary": "Assign a conversation", "description": "Assigns the current session to a member of the company (GET /conversations/assignees), or unassigns it with null.", "operationId": "assignConversation", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "user_id" ], "properties": { "user_id": { "type": [ "string", "null" ], "example": "USR-XXXXX" } }, "type": "object" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/Conversation" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/conversations/assignees": { "get": { "tags": [ "Conversations" ], "summary": "List assignees", "description": "Members of the company a conversation can be assigned to.", "operationId": "listAssignees", "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "type": "array", "items": { "$ref": "#/components/schemas/Member" } } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/deep-links": { "get": { "tags": [ "Dynamic links" ], "summary": "List dynamic links", "description": "Most recent first, 50 per page. Search the names with `name`.", "operationId": "listDeepLinks", "parameters": [ { "name": "name", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "allOf": [ { "$ref": "#/components/schemas/ApiPage" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DeepLink" } } }, "type": "object" } ] } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Dynamic links" ], "summary": "Create a dynamic link", "description": "Share `link`: it opens the app (or its store) on the phone, and fallback_url elsewhere. Serve the verification file of each app on its domain (`GET /deep-links/platforms/{id}/verification-file`).", "operationId": "createDeepLink", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepLinkInput" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/DeepLink" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/deep-links/{id}": { "get": { "tags": [ "Dynamic links" ], "summary": "Get a dynamic link", "operationId": "getDeepLink", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "DLK-XXXXX" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/DeepLink" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Dynamic links" ], "summary": "Delete a dynamic link", "description": "The link stops working, with its click history.", "operationId": "deleteDeepLink", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The deleted DeepLink", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/DeepLink" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "tags": [ "Dynamic links" ], "summary": "Update a dynamic link", "description": "Partial update (PUT is accepted too). Changing short_code changes the link: the previous one stops working.", "operationId": "updateDeepLink", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepLinkInput" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/DeepLink" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/deep-links/{id}/clicks": { "get": { "tags": [ "Dynamic links" ], "summary": "Clicks of a dynamic link", "description": "Most recent first, 50 per page.", "operationId": "listDeepLinkClicks", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "allOf": [ { "$ref": "#/components/schemas/ApiPage" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DeepLinkClick" } } }, "type": "object" } ] } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/follow-ups": { "get": { "tags": [ "Follow-ups" ], "summary": "List follow-ups", "description": "Next follow-up first, 50 per page. Filter with `status`, `conversation_id`, `type_id` and `campaign_id`.", "operationId": "listFollowUps", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "scheduled", "resolved", "exhausted", "cancelled", "failed" ] } }, { "name": "conversation_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "type_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "campaign_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "allOf": [ { "$ref": "#/components/schemas/ApiPage" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FollowUp" } } }, "type": "object" } ] } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Follow-ups" ], "summary": "Schedule a follow-up", "description": "Follow-ups are sent until the contact replies, at the interval and up to the maximum of the type (or of its override for the sender). The text is written by the AI from `reason`, unless `message` is given. When a follow-up of the same type is already scheduled on the conversation, that one is returned.", "operationId": "createFollowUp", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowUpInput" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/FollowUp" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/follow-ups/{id}": { "get": { "tags": [ "Follow-ups" ], "summary": "Get a follow-up", "operationId": "getFollowUp", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "FUP-XXXXX" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/FollowUp" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/follow-ups/{id}/reschedule": { "post": { "tags": [ "Follow-ups" ], "summary": "Reschedule a follow-up", "description": "Moves the next follow-up of a scheduled one.", "operationId": "rescheduleFollowUp", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "scheduled_at" ], "properties": { "scheduled_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/FollowUp" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/follow-ups/{id}/resolve": { "post": { "tags": [ "Follow-ups" ], "summary": "Resolve a follow-up", "description": "The goal is reached: no more follow-ups are sent.", "operationId": "resolveFollowUp", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "note": { "type": [ "string", "null" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/FollowUp" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/follow-ups/{id}/cancel": { "post": { "tags": [ "Follow-ups" ], "summary": "Cancel a follow-up", "description": "No more follow-ups are sent.", "operationId": "cancelFollowUp", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "note": { "type": [ "string", "null" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/FollowUp" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/follow-up-types": { "get": { "tags": [ "Follow-ups" ], "summary": "List follow-up types", "description": "By name, 50 per page. Filter with `active`.", "operationId": "listFollowUpTypes", "parameters": [ { "name": "active", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "allOf": [ { "$ref": "#/components/schemas/ApiPage" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FollowUpType" } } }, "type": "object" } ] } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Follow-ups" ], "summary": "Create a follow-up type", "operationId": "createFollowUpType", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowUpTypeInput" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/FollowUpType" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/follow-up-types/{id}": { "get": { "tags": [ "Follow-ups" ], "summary": "Get a follow-up type", "operationId": "getFollowUpType", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "FUI-XXXXX" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/FollowUpType" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Follow-ups" ], "summary": "Delete a follow-up type", "description": "Its follow-ups already scheduled still go out; set `active` to false to stop new ones only.", "operationId": "deleteFollowUpType", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The deleted type", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/FollowUpType" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "tags": [ "Follow-ups" ], "summary": "Update a follow-up type", "description": "Partial update (PUT is accepted too). Scheduled follow-ups use the new settings from their next round.", "operationId": "updateFollowUpType", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowUpTypeInput" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/FollowUpType" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/me": { "get": { "tags": [ "Account" ], "summary": "Current API key", "description": "Company and API key behind the token. Call it first to check your integration.", "operationId": "getMe", "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/Me" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/channels/shortext": { "post": { "tags": [ "Channels" ], "summary": "Create a Shortext endpoint", "description": "Your server then posts the messages of your users to settings.inbound_url with your API key and `to` = the endpoint id. With a webhook_url, the response holds `webhook_secret` once: keep it to verify the signature of the replies.", "operationId": "createShortextEndpoint", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShortextEndpointInput" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "allOf": [ { "$ref": "#/components/schemas/Channel" }, { "properties": { "webhook_secret": { "description": "Signing secret of the replies, only when the webhook is created or rotated", "type": "string" } }, "type": "object" } ] } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/channels/shortext/{id}": { "delete": { "tags": [ "Channels" ], "summary": "Delete a Shortext endpoint", "description": "Final: the endpoint stops receiving and its conversations leave the inbox (kept for audits).", "operationId": "deleteShortextEndpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The deleted Channel", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/Channel" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "tags": [ "Channels" ], "summary": "Update a Shortext endpoint", "description": "Partial update: only the fields sent change (PUT is accepted too). Setting a webhook_url for the first time returns its `webhook_secret`.", "operationId": "updateShortextEndpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "ste_xxx" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShortextEndpointInput" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/Channel" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/channels/shortext/{id}/rotate-secret": { "post": { "tags": [ "Channels" ], "summary": "Rotate the webhook signing secret", "description": "The previous secret stops working at once: update your verification first.", "operationId": "rotateShortextWebhookSecret", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "allOf": [ { "$ref": "#/components/schemas/Channel" }, { "properties": { "webhook_secret": { "description": "Signing secret of the replies, only when the webhook is created or rotated", "type": "string" } }, "type": "object" } ] } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{agent}/sla-policies": { "get": { "tags": [ "Tickets" ], "summary": "List SLA policies", "description": "Shortest response time first. Tickets refer to a policy by its `priority` code.", "operationId": "listSlaPolicies", "parameters": [ { "name": "agent", "in": "path", "required": true, "schema": { "type": "string", "example": "AGI-XXXXX" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "allOf": [ { "$ref": "#/components/schemas/ApiPage" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SlaPolicy" } } }, "type": "object" } ] } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Tickets" ], "summary": "Create an SLA policy", "description": "Times are working minutes, Monday to Friday from 8:00 to 18:00.", "operationId": "createSlaPolicy", "parameters": [ { "name": "agent", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlaPolicyInput" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/SlaPolicy" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{agent}/sla-policies/{priority}": { "get": { "tags": [ "Tickets" ], "summary": "Get an SLA policy", "operationId": "getSlaPolicy", "parameters": [ { "name": "agent", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "priority", "in": "path", "required": true, "schema": { "type": "string", "example": "high" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/SlaPolicy" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Tickets" ], "summary": "Delete an SLA policy", "description": "Refused while open tickets have this priority; resolved and closed tickets lose it.", "operationId": "deleteSlaPolicy", "parameters": [ { "name": "agent", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "priority", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The deleted SlaPolicy", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/SlaPolicy" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "tags": [ "Tickets" ], "summary": "Update an SLA policy", "description": "Partial update (PUT is accepted too). New times apply to the tickets that get this priority afterwards; renaming changes the priority code.", "operationId": "updateSlaPolicy", "parameters": [ { "name": "agent", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "priority", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlaPolicyInput" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/SlaPolicy" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/channels/telegram": { "post": { "tags": [ "Channels" ], "summary": "Connect a Telegram bot", "description": "The token is checked with Telegram and the bot starts receiving at once. A bot can be connected once only. Your customers write to `https://t.me/` and tap Start; add `?start=` (64 characters at most, letters, digits, _ and -) to know where they come from.", "operationId": "createTelegramBot", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramBotInput" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/Channel" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/channels/telegram/{id}": { "delete": { "tags": [ "Channels" ], "summary": "Delete a Telegram bot", "description": "Final: the bot stops receiving and its conversations leave the inbox (kept for audits). The bot itself stays yours in @BotFather.", "operationId": "deleteTelegramBot", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The deleted Channel", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/Channel" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "tags": [ "Channels" ], "summary": "Update a Telegram bot", "description": "Partial update: only the fields sent change (PUT is accepted too). Disabling stops the reception, enabling installs it again.", "operationId": "updateTelegramBot", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "tga_xxx" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramBotInput" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/Channel" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/templates": { "get": { "tags": [ "Templates" ], "summary": "List WhatsApp templates", "description": "Templates of the WhatsApp Business Accounts of the company numbers, most recently updated first, 50 per page.", "operationId": "listTemplates", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "channel_id", "in": "query", "description": "Only the templates this WhatsApp number can send", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "APPROVED", "PENDING", "REJECTED" ] } }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "allOf": [ { "$ref": "#/components/schemas/ApiPage" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Template" } } }, "type": "object" } ] } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Templates" ], "summary": "Create a WhatsApp template", "description": "Checked against Meta's rules, then sent to Meta for review: the template is PENDING until Meta approves it (webhook `template.status_updated`). Refused by Meta: nothing is kept and the error says why.", "operationId": "createTemplate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateInput" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/Template" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/templates/{id}": { "get": { "tags": [ "Templates" ], "summary": "Get a WhatsApp template", "operationId": "getTemplate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/Template" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "tags": [ "Templates" ], "summary": "Edit a WhatsApp template", "description": "Header, body, footer, buttons or authentication settings; name, language and category stay. Sent to Meta for a new review (Meta limits the edits of an approved template); refused by Meta, the template stays as it was. A published authentication template cannot be edited.", "operationId": "updateTemplate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateInput" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/Template" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/tickets": { "get": { "tags": [ "Tickets" ], "summary": "List tickets", "description": "Most recent first, 50 per page.", "operationId": "listTickets", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "state", "in": "query", "description": "`open` (neither resolved nor closed), `resolved` or `closed`", "required": false, "schema": { "type": "string", "enum": [ "open", "resolved", "closed" ] } }, { "name": "status", "in": "query", "description": "Status code, several separated by commas", "required": false, "schema": { "type": "string" } }, { "name": "priority", "in": "query", "description": "Priority code, several separated by commas", "required": false, "schema": { "type": "string" } }, { "name": "agent_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "conversation_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "breached", "in": "query", "description": "Only tickets past one of their SLA due dates", "required": false, "schema": { "type": "boolean" } }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "allOf": [ { "$ref": "#/components/schemas/ApiPage" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Ticket" } } }, "type": "object" } ] } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Tickets" ], "summary": "Open a ticket", "description": "Opens a ticket on a conversation: the agent of its channel owns it. Its members are notified.", "operationId": "createTicket", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketInput" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/Ticket" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/tickets/{id}": { "get": { "tags": [ "Tickets" ], "summary": "Get a ticket", "operationId": "getTicket", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "STT-XXXXX" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/Ticket" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "tags": [ "Tickets" ], "summary": "Update a ticket", "description": "Partial update (PUT is accepted too). Change `status` to move, resolve, close or reopen the ticket. `conversation_id` cannot change.", "operationId": "updateTicket", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketInput" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/Ticket" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/tickets/{id}/activities": { "get": { "tags": [ "Tickets" ], "summary": "Ticket activity", "description": "Oldest first: status changes, internal notes, answers to the contact, SLA breaches.", "operationId": "listTicketActivities", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "type": "array", "items": { "$ref": "#/components/schemas/TicketActivity" } } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/tickets/{id}/comments": { "post": { "tags": [ "Tickets" ], "summary": "Add a note", "description": "Internal note: the contact does not see it.", "operationId": "commentTicket", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "text" ], "properties": { "text": { "type": "string", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/TicketActivity" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/tickets/{id}/responses": { "post": { "tags": [ "Tickets" ], "summary": "Answer the contact", "description": "Sent to the contact on the conversation of the ticket, with the ticket reference (a notification template outside the WhatsApp 24h window). The first answer sets responded_at.", "operationId": "respondTicket", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "text" ], "properties": { "text": { "type": "string", "maxLength": 5000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/TicketActivity" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{agent}/ticket-statuses": { "get": { "tags": [ "Tickets" ], "summary": "List ticket statuses", "description": "In board order.", "operationId": "listTicketStatuses", "parameters": [ { "name": "agent", "in": "path", "required": true, "schema": { "type": "string", "example": "AGI-XXXXX" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "allOf": [ { "$ref": "#/components/schemas/ApiPage" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TicketStatus" } } }, "type": "object" } ] } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Tickets" ], "summary": "Create a ticket status", "operationId": "createTicketStatus", "parameters": [ { "name": "agent", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketStatusInput" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/TicketStatus" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/agents/{agent}/ticket-statuses/{code}": { "get": { "tags": [ "Tickets" ], "summary": "Get a ticket status", "operationId": "getTicketStatus", "parameters": [ { "name": "agent", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "example": "in_progress" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/TicketStatus" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Tickets" ], "summary": "Delete a ticket status", "description": "Refused while tickets have this status: move them first, or set `active` to false.", "operationId": "deleteTicketStatus", "parameters": [ { "name": "agent", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The deleted TicketStatus", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/TicketStatus" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "tags": [ "Tickets" ], "summary": "Update a ticket status", "description": "Partial update (PUT is accepted too). Renaming changes the code.", "operationId": "updateTicketStatus", "parameters": [ { "name": "agent", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketStatusInput" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/TicketStatus" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/hosted-sessions/purposes": { "get": { "tags": [ "Hosted sessions" ], "summary": "Purposes of the hosted sessions", "operationId": "listHostedSessionPurposes", "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "allOf": [ { "description": "purpose => description", "type": "object", "additionalProperties": { "type": "string" } } ] } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/hosted-sessions": { "get": { "tags": [ "Hosted sessions" ], "summary": "List hosted sessions", "description": "Most recent first, 50 per page.", "operationId": "listHostedSessions", "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "allOf": [ { "$ref": "#/components/schemas/ApiPage" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/HostedSession" } } }, "type": "object" } ] } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Hosted sessions" ], "summary": "Create a hosted session", "description": "Returns the `url` of a page hosted by us, to give to your user (redirect or new window, not an iframe). It expires and serves once. Follow the outcome with `GET /hosted-sessions/{id}` or the webhooks.", "operationId": "createHostedSession", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostedSessionInput" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "allOf": [ { "$ref": "#/components/schemas/HostedSession" }, { "properties": { "url": { "description": "The page to give to your user (holds a secret)", "type": "string" } }, "type": "object" } ] } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/hosted-sessions/{id}": { "get": { "tags": [ "Hosted sessions" ], "summary": "Get a hosted session", "operationId": "getHostedSession", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/HostedSession" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Hosted sessions" ], "summary": "Cancel a hosted session", "description": "The URL stops working. A finished session cannot be cancelled.", "operationId": "cancelHostedSession", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/HostedSession" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/webhooks/events": { "get": { "tags": [ "Webhooks" ], "summary": "Webhook event catalog", "description": "Event types an endpoint can subscribe to. Subscribe with an exact type, a prefix wildcard such as `message.*`, or `*`.", "operationId": "listWebhookEvents", "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "allOf": [ { "type": "array", "items": { "properties": { "type": { "type": "string" }, "description": { "type": "string" } }, "type": "object" } } ] } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List webhook endpoints", "operationId": "listWebhooks", "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Webhooks" ], "summary": "Create a webhook endpoint", "description": "The signing `secret` is returned **only once**, keep it. Payloads follow the API version used to create the endpoint.", "operationId": "createWebhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointInput" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "allOf": [ { "$ref": "#/components/schemas/WebhookEndpoint" }, { "properties": { "secret": { "description": "Signing secret, shown only here", "type": "string" } }, "type": "object" } ] } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/webhooks/{id}": { "get": { "tags": [ "Webhooks" ], "summary": "Get a webhook endpoint", "operationId": "getWebhook", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Webhooks" ], "summary": "Update a webhook endpoint", "description": "Setting `is_enabled` to true re-enables an endpoint disabled after repeated failures.", "operationId": "updateWebhook", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointInput" } } } }, "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete a webhook endpoint", "operationId": "deleteWebhook", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "allOf": [ { "type": "null" } ] } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/webhooks/{id}/rotate-secret": { "post": { "tags": [ "Webhooks" ], "summary": "Rotate the signing secret", "description": "The previous secret stops working immediately.", "operationId": "rotateWebhookSecret", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "properties": { "secret": { "description": "The new signing secret", "type": "string" } }, "type": "object" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/webhooks/{id}/test": { "post": { "tags": [ "Webhooks" ], "summary": "Send a test event", "description": "Sends a `webhook.test` event right away (no retry) and returns the delivery with the endpoint response.", "operationId": "testWebhook", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/WebhookDelivery" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/webhooks/{id}/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "Delivery history", "description": "Most recent first, 50 per page. Deliveries are kept 30 days.", "operationId": "listWebhookDeliveries", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "succeeded", "failed" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "allOf": [ { "$ref": "#/components/schemas/ApiPage" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } }, "type": "object" } ] } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/webhooks/{id}/deliveries/{delivery}/retry": { "post": { "tags": [ "Webhooks" ], "summary": "Redeliver an event", "description": "Queues a new delivery of the same event (same event `id`).", "operationId": "retryWebhookDelivery", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "delivery", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The new WebhookDelivery", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiEnvelope" }, { "properties": { "body": { "$ref": "#/components/schemas/WebhookDelivery" } }, "type": "object" } ] } } } } }, "security": [ { "bearerAuth": [] } ] } } }, "components": { "schemas": { "Balance": { "properties": { "balance": { "description": "In the billing currency", "properties": { "amount": { "description": "Balance of the actor company and the movements of its wallet (read only: top-ups happen in the dashboard)", "type": "number", "example": 590.88 }, "currency": { "type": "string", "example": "EUR" } }, "type": "object" }, "local_balance": { "description": "Converted to the currency of the company country, for information", "properties": { "amount": { "type": "number", "example": 387590 }, "currency": { "type": "string", "example": "XAF" } }, "type": [ "object", "null" ] }, "threshold": { "description": "Under this amount the company is warned to top up", "properties": { "amount": { "type": "number" }, "currency": { "type": "string" } }, "type": "object" }, "low": { "description": "The balance is under the threshold", "type": "boolean" } }, "type": "object" }, "BalanceTransaction": { "properties": { "id": { "type": "string" }, "amount": { "description": "Negative for a debit (messages, AI, subscriptions), positive for a top-up", "type": "number", "example": -0.10613 }, "currency": { "type": "string", "example": "EUR" }, "description": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "StartConversationInput": { "required": [ "channel", "channel_id", "contact", "message" ], "properties": { "channel": { "type": "string", "enum": [ "whatsapp", "mail", "shortext", "telegram" ] }, "channel_id": { "description": "Your channel id (`GET /channels`): WhatsApp phone id, mailbox id (mbx_...) or Shortext endpoint id (ste_...)", "type": "string" }, "contact": { "properties": { "identifier": { "description": "Phone (E.164 without +), email or, on Shortext, any identifier typed by identifier_type", "type": "string" }, "identifier_type": { "description": "Shortext only, external_id by default. phone and email are matched with the same contact on WhatsApp and email.", "type": "string", "enum": [ "external_id", "phone", "email", "username" ] }, "profile": { "properties": { "lastname": { "type": "string" }, "firstname": { "type": "string" }, "email": { "type": "string" }, "preferred_language": { "type": "string", "enum": [ "en", "fr", "es", "de" ] } }, "type": "object" } }, "type": "object" }, "message": { "$ref": "#/components/schemas/MessageInput" }, "handover": { "description": "true: a human follows the conversation, the AI agent does not answer the contact", "type": "boolean", "default": false } }, "type": "object" }, "Me": { "properties": { "company": { "properties": { "id": { "type": "string", "example": "CMP-XXXXX" }, "name": { "type": "string", "example": "Acme" } }, "type": "object" }, "token": { "properties": { "name": { "type": "string", "example": "CRM integration" }, "abilities": { "type": "array", "items": { "type": "string" }, "example": [ "send_messages" ] }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } }, "type": "object" }, "api_version": { "type": "string", "example": "v2.0" } }, "type": "object" }, "ShortextEndpointInput": { "properties": { "name": { "description": "Required on creation", "type": "string", "maxLength": 255 }, "agent_id": { "description": "Agent answering on the endpoint; null detaches it", "type": [ "string", "null" ], "example": "AGI-XXXXX" }, "enabled": { "type": "boolean", "default": true }, "reply_mode": { "description": "`async`: replies pushed to webhook_url (signed); `sync`: replies in the response of the inbound call", "type": "string", "default": "async", "enum": [ "async", "sync" ] }, "sync_timeout": { "description": "Seconds the sync mode waits for the replies", "type": "integer", "default": 25, "maximum": 25, "minimum": 1 }, "webhook_url": { "description": "Where the replies are pushed (https); null removes it", "type": [ "string", "null" ] } }, "type": "object" }, "TelegramBotInput": { "properties": { "bot_token": { "description": "Token given by @BotFather (/newbot). Required on creation; on update only to replace a regenerated token of the same bot. Never returned.", "type": "string", "example": "123456789:AAH..." }, "name": { "description": "Internal name, the name of the bot by default", "type": "string", "maxLength": 255 }, "agent_id": { "description": "Agent answering on the bot; null detaches it", "type": [ "string", "null" ], "example": "AGI-XXXXX" }, "enabled": { "description": "Disabled, the bot no longer receives messages", "type": "boolean", "default": true } }, "type": "object" }, "TemplateInput": { "properties": { "channel_id": { "description": "Creation: a WhatsApp number of the company; the template belongs to its WhatsApp Business Account and every number of that account can send it", "type": "string" }, "name": { "description": "Creation: normalized for Meta (`Order update` becomes `order_update`)", "type": "string" }, "language": { "description": "Creation", "type": "string", "example": "fr" }, "category": { "description": "Creation. A utility body has at least one variable; an authentication template only takes `authentication`", "type": "string", "enum": [ "MARKETING", "UTILITY", "AUTHENTICATION" ] }, "header": { "properties": { "type": { "type": "string", "enum": [ "NONE", "TEXT", "IMAGE", "VIDEO", "DOCUMENT" ] }, "text": { "description": "TEXT: 60 characters, one variable at most", "type": "string" }, "examples": { "description": "`{ variable: example }`", "type": "object" }, "media_url": { "description": "IMAGE, VIDEO, DOCUMENT: a public link to the file", "type": "string" } }, "type": "object" }, "body": { "properties": { "text": { "description": "Variables like `{{order_number}}`, not at the very start or end", "type": "string", "example": "Hello {{name}}, your order {{order_number}} is ready." }, "examples": { "description": "One example per variable: Meta reviews the template with them", "type": "object", "example": { "name": "Awa", "order_number": "A-42" } } }, "type": "object" }, "footer": { "description": "60 characters, no variable", "type": [ "string", "null" ] }, "buttons": { "description": "Up to 10: quick replies grouped together, 2 links, 1 call, 1 copy code (marketing). A link with `{{1}}` at the end of the URL needs an `example`", "type": "array", "items": { "properties": { "type": { "type": "string", "enum": [ "QUICK_REPLY", "URL", "PHONE_NUMBER", "COPY_CODE" ] }, "text": { "type": "string", "maxLength": 25 }, "url": { "type": "string", "example": "https://shop.example/orders/{{1}}" }, "example": { "description": "URL: the full example link; COPY_CODE: an example code", "type": "string" }, "phone_number": { "type": "string", "example": "+237690000000" } }, "type": "object" } }, "authentication": { "properties": { "add_security_recommendation": { "type": "boolean", "default": true }, "code_expiration_minutes": { "type": [ "integer", "null" ], "maximum": 90, "minimum": 1 }, "otp_type": { "type": "string", "default": "COPY_CODE", "enum": [ "COPY_CODE", "ONE_TAP" ] }, "package_name": { "description": "ONE_TAP: the Android app", "type": "string" }, "signature_hash": { "description": "ONE_TAP: 11 characters", "type": "string" } }, "type": "object" } }, "type": "object" }, "Agent": { "properties": { "id": { "description": "Public representation of an agent (API v2.0 and webhooks)", "type": "string", "example": "AGI-XXXXX" }, "name": { "type": "string", "example": "Support" }, "active": { "description": "An inactive agent stores messages without answering", "type": "boolean" }, "use_ai": { "description": "The AI answers, following the instructions", "type": "boolean" }, "inactive_message": { "description": "Fixed answer when the AI is off", "type": [ "string", "null" ] }, "instructions": { "description": "System prompt of the AI", "type": [ "string", "null" ] }, "channels": { "description": "Not in webhook payloads", "type": "array", "items": { "$ref": "#/components/schemas/Channel" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "AgentInput": { "properties": { "name": { "description": "Required on creation", "type": "string", "maxLength": 255 }, "active": { "type": "boolean", "default": true }, "use_ai": { "type": "boolean", "default": true }, "inactive_message": { "type": [ "string", "null" ], "maxLength": 1000 }, "instructions": { "description": "System prompt; empty or null removes it", "type": [ "string", "null" ], "maxLength": 15000 } }, "type": "object" }, "Campaign": { "properties": { "id": { "description": "Public representation of campaigns, their contact files and segments (API v2.0)", "type": "string", "example": "CMP-XXXXX" }, "name": { "type": "string" }, "category": { "type": "string", "enum": [ "marketing", "transactional", "specialized" ] }, "objective": { "type": [ "string", "null" ] }, "trigger": { "description": "`scheduled`: sent once to an audience. `new_conversation`: sent on each new conversation while active.", "type": "string", "enum": [ "scheduled", "new_conversation" ] }, "status": { "type": "string", "enum": [ "draft", "scheduled", "active", "paused", "ended", "failed" ] }, "failure_reason": { "type": [ "string", "null" ] }, "once_per_contact": { "description": "Automatic campaigns: a contact gets the message once", "type": [ "boolean", "null" ] }, "channels": { "type": "array", "items": { "properties": { "channel": { "type": "string", "enum": [ "whatsapp", "mail" ] }, "channel_id": { "description": "The sender: WhatsApp phone number id or mailbox id (mbx_...)", "type": "string" } }, "type": "object" } }, "messages": { "description": "One message per channel, by channel", "type": "object", "example": { "whatsapp": { "type": "template", "template": { "id": "TPL-XXXXX", "name": "promo", "language": "fr" }, "variables": { "name": { "source": "field:firstname", "fallback": "client" } }, "buttons": [ "promo-@firstname" ] }, "mail": { "type": "email", "subject": "Our offer, @{firstname|dear customer}" } } }, "audience": { "properties": { "source": { "type": "string", "enum": [ "segment", "file", "contacts" ] }, "segment_id": { "type": [ "string", "null" ] }, "import_id": { "type": [ "string", "null" ] }, "recipients": { "description": "Recipients written to the campaign (a segment is evaluated when it starts)", "type": "integer" } }, "type": "object" }, "start_at": { "type": [ "string", "null" ], "format": "date-time" }, "end_at": { "description": "Replies count for the campaign until this date", "type": [ "string", "null" ], "format": "date-time" }, "send_window": { "description": "Hours of the day it may send, in the company time zone", "properties": { "start": { "type": "string", "example": "08:00" }, "end": { "type": "string", "example": "20:00" } }, "type": [ "object", "null" ] }, "follow_up_intention_ids": { "type": "array", "items": { "type": "string" } }, "paused_at": { "type": [ "string", "null" ], "format": "date-time" }, "duplicated_from": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "CampaignInput": { "description": "On update, only the fields given change. A scheduled or running campaign cannot be edited: pause it first.", "properties": { "name": { "description": "Required on creation", "type": "string", "maxLength": 255 }, "category": { "description": "Required on creation. Contacts who unsubscribed get no marketing campaign.", "type": "string", "enum": [ "marketing", "transactional", "specialized" ] }, "objective": { "type": [ "string", "null" ] }, "trigger": { "description": "Required on creation", "type": "string", "enum": [ "scheduled", "new_conversation" ] }, "once_per_contact": { "type": "boolean" }, "send_delay_minutes": { "description": "Automatic campaigns: wait after the conversation starts", "type": "integer" }, "min_inactive_minutes": { "description": "Automatic campaigns: wait for the conversation to be quiet", "type": "integer" }, "channels": { "description": "The senders, by their channel_id (GET /channels)", "type": "array", "items": { "properties": { "channel_id": { "type": "string" } }, "type": "object" } }, "messages": { "description": "`whatsapp`: `{ template_id, variables: { name: { source, value?, fallback? } }, buttons?: { index: value }, header_url? }` (source: `field:firstname|lastname|name|email|phone|address|identifier`, `column:` of the imported file, or `text` with `value`); an automatic campaign may send `{ text }` instead. `mail`: `{ subject, html }`. Texts accept `@firstname`, `@` and `@{key|fallback}`.", "type": "object" }, "audience": { "description": "Scheduled campaigns: `{ source: \"segment\", segment_id }`, `{ source: \"file\", import_id, save_as_segment? }` (a checked file, POST /campaign-imports) or `{ source: \"contacts\", contact_ids }`", "type": "object" }, "start_at": { "type": [ "string", "null" ], "format": "date-time" }, "end_at": { "description": "Required to launch", "type": "string", "format": "date-time" }, "send_window": { "type": [ "object", "null" ], "example": { "start": "08:00", "end": "20:00" } }, "follow_up_intention_ids": { "type": "array", "items": { "type": "string" } } }, "type": "object" }, "CampaignCheck": { "properties": { "key": { "type": "string", "enum": [ "senders", "messages", "template", "audience", "variables", "dates", "credit" ] }, "state": { "description": "`block` stops the launch", "type": "string", "enum": [ "ok", "warn", "block" ] }, "label": { "type": "string" }, "detail": { "type": [ "string", "null" ] } }, "type": "object" }, "CampaignEstimate": { "properties": { "currency": { "type": "string", "example": "EUR" }, "total": { "type": "number" }, "channels": { "type": "array", "items": { "properties": { "channel": { "type": "string" }, "recipients": { "type": "integer" }, "cost": { "type": "number" } }, "type": "object" } }, "plan_remaining": { "description": "Left in the plan, when the company has one", "type": [ "number", "null" ] }, "balance": { "type": "number" }, "balance_after": { "type": "number" } }, "type": "object" }, "CampaignReport": { "description": "A message that failed counts as failed only (an email accepted then bounced, for example): sent + failed = attempted, and no rate goes over 100.", "properties": { "counts": { "description": "total, queued, attempted (sent or failed), sent, delivered, read, responded, failed", "type": "object" }, "rates": { "description": "Percentages, each on its own base: delivery = delivered / attempted, open = read / delivered, response = responded / read, intention = intentions / responded, failure = failed / attempted", "type": "object" }, "comparison": { "description": "Each rate next to its average over your ended campaigns (same category when there are some), and the gap in points (null before the first send)", "type": "object" }, "funnel": { "description": "attempted, delivered, read, responded, intentions: count and rate on the step before", "type": "array", "items": { "type": "object" } }, "timelines": { "description": "Average delays in seconds, on real receipt dates", "type": "object" }, "hourly": { "description": "Reads and replies per hour since the first send (72 hours), with the peak reply hour of the day", "type": "object" }, "failures": { "description": "Failures by motif: no_whatsapp, invalid_number, email_refused, limit_reached, template_refused, insufficient_credit, other", "type": "array", "items": { "type": "object" } }, "intentions": { "description": "Recipients with a follow-up intention, and per intention: count and how many went on to a ticket", "type": "object" }, "return": { "description": "cost, revenue (orders of a recipient within 7 days after receipt), orders, profit, roi_multiple (revenue per unit spent), cost_per_message, cost_per_response", "type": "object" }, "progress": { "description": "done, total, percent, estimated_end_at (while sending), postponed (to the next opening of the send window)", "type": "object" }, "source": { "description": "type: segment (name), file (name, rows, rejected), manual (contacts) or automatic", "type": "object" }, "channels": { "type": "array", "items": { "type": "object" } }, "cost": { "description": "Charged so far (same as return.cost)", "type": "number" } }, "type": "object" }, "CampaignRecipient": { "properties": { "contact": { "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "identifier": { "description": "Where the message went: phone number, or email address on the email channel", "type": [ "string", "null" ] } }, "type": "object" }, "channel": { "type": "string", "example": "whatsapp" }, "status": { "type": "string", "enum": [ "waiting", "queued", "sending", "sent", "delivered", "read", "responded", "failed" ] }, "last_event": { "type": [ "string", "null" ], "format": "date-time" }, "failure": { "properties": { "reason": { "type": "string", "enum": [ "no_whatsapp", "invalid_number", "email_refused", "limit_reached", "template_refused", "insufficient_credit", "other" ] }, "detail": { "description": "The channel's message", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] } }, "type": "object" }, "CampaignImport": { "properties": { "id": { "type": "string", "example": "IMP-XXXXX" }, "file_name": { "type": "string" }, "rows": { "type": "integer" }, "has_header": { "type": "boolean" }, "status": { "type": "string", "enum": [ "uploaded", "mapped", "checking", "checked", "applying", "validated", "failed" ] }, "columns": { "type": "array", "items": { "properties": { "index": { "type": "integer" }, "header": { "type": "string" }, "samples": { "type": "array", "items": { "type": "string" } }, "target": { "description": "`phone` (required), `first_name`, `last_name`, `email`, `var:` (a variable for the message) or `ignore`", "type": "string" } }, "type": "object" } }, "report": { "description": "After the check: rows, valid, duplicates, invalid (with invalid_rows: row, value, reason), opted_out, new_contacts", "type": [ "object", "null" ] } }, "type": "object" }, "CampaignSegment": { "properties": { "id": { "type": "string", "example": "SEG-XXXXX" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "description": "`rules`: contacts matching its rules when the campaign starts. `list`: a fixed list (saved from a file).", "type": "string", "enum": [ "rules", "list" ] } }, "type": "object" }, "Channel": { "properties": { "type": { "description": "Public representation of a channel (API v2.0 and webhooks). The id is the one webhooks use as channel_id.", "type": "string", "enum": [ "whatsapp", "mail", "shortext", "telegram" ], "example": "whatsapp" }, "id": { "description": "Channel id (the channel_id of the webhooks): WhatsApp phone number id, mailbox id (mbx_...), Shortext endpoint id (ste_...) or Telegram bot id (tga_...)", "type": "string", "example": "532867649916076" }, "name": { "type": "string", "example": "+237 6 99 99 99 99 (Acme)" }, "enabled": { "type": "boolean" }, "agent": { "description": "null when the channel is detached: messages are stored, nobody answers automatically", "properties": { "id": { "type": "string", "example": "AGI-XXXXX" }, "name": { "type": "string" } }, "type": [ "object", "null" ] }, "settings": { "description": "Shortext: endpoint settings. Telegram: username, bot_url, receiving, last_error. Null for the other channels", "properties": { "client_type": { "type": "string", "example": "server" }, "inbound_url": { "description": "Where your server posts the messages of your users", "type": "string" }, "reply_mode": { "description": "`async`: replies pushed to webhook_url; `sync`: replies in the inbound response", "type": "string", "enum": [ "async", "sync" ] }, "sync_timeout": { "description": "Seconds the sync mode waits for the replies", "type": "integer" }, "webhook_url": { "type": [ "string", "null" ] }, "username": { "description": "Telegram: the @username of the bot, without @", "type": "string" }, "bot_url": { "description": "Telegram: link your customers open (add ?start= to know where they come from)", "type": "string", "example": "https://t.me/AcmeBot" }, "receiving": { "description": "Telegram: the bot is enabled and Telegram delivers its messages", "type": "boolean" }, "last_error": { "description": "Telegram: last refusal of Telegram, null when all is well", "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "Conversation": { "properties": { "id": { "description": "The conversation_id of the webhooks", "type": "string" }, "status": { "description": "`active`: a session is open; `archived`: replying opens a new one", "type": "string", "enum": [ "active", "archived" ] }, "channel": { "properties": { "type": { "type": "string", "enum": [ "whatsapp", "mail", "shortext" ] }, "id": { "description": "The channel_id of the webhooks", "type": "string" } }, "type": "object" }, "agent": { "description": "Agent answering on the channel; null when the channel is detached", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "type": [ "object", "null" ] }, "contact": { "properties": { "identifier": { "type": "string" }, "identifier_type": { "type": "string" }, "profile": { "type": "object" }, "country": { "type": "object" } }, "type": "object" }, "session": { "description": "Current session; null when archived", "properties": { "started_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": [ "string", "null" ], "format": "date-time" }, "handover": { "description": "A human took over: the AI agent does not answer", "type": "boolean" }, "handover_at": { "type": [ "string", "null" ], "format": "date-time" }, "assignee": { "oneOf": [ { "$ref": "#/components/schemas/Member" }, { "type": "null" } ] } }, "type": [ "object", "null" ] }, "last_message_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "Member": { "description": "User of the company (dashboard, mobile app)", "properties": { "id": { "type": "string", "example": "USR-XXXXX" }, "name": { "type": "string" } }, "type": "object" }, "DeepLink": { "properties": { "id": { "description": "Public representation of dynamic links, the apps they open and their clicks (API v2.0)", "type": "string", "example": "DLK-XXXXX" }, "name": { "type": "string" }, "short_code": { "type": "string", "example": "promo-oct" }, "link": { "description": "The short URL to share", "type": "string", "example": "https://shortext.ny-corp.io/s/promo-oct" }, "deep_link": { "description": "Opened in the app when it is installed", "type": "string" }, "fallback_url": { "description": "Opened on a computer, or when no app matches", "type": "string" }, "description": { "type": [ "string", "null" ] }, "expire_at": { "type": [ "string", "null" ], "format": "date-time" }, "android_platform": { "oneOf": [ { "$ref": "#/components/schemas/AppPlatform" }, { "type": "null" } ] }, "ios_platform": { "oneOf": [ { "$ref": "#/components/schemas/AppPlatform" }, { "type": "null" } ] }, "clicks": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "DeepLinkInput": { "properties": { "name": { "description": "Required on creation, unique in the company", "type": "string", "maxLength": 255 }, "short_code": { "description": "Path of the short URL; generated when absent", "type": "string", "maxLength": 50, "pattern": "^[A-Za-z0-9_-]+$" }, "deep_link": { "description": "Required on creation", "type": "string", "format": "uri" }, "fallback_url": { "description": "Required on creation", "type": "string", "format": "uri" }, "description": { "type": [ "string", "null" ], "maxLength": 300 }, "expire_at": { "type": [ "string", "null" ], "format": "date-time" }, "android_platform_id": { "description": "An Android app (GET /deep-links/platforms); at least one platform", "type": [ "string", "null" ] }, "ios_platform_id": { "description": "An iOS app; at least one platform", "type": [ "string", "null" ] } }, "type": "object" }, "AppPlatform": { "properties": { "id": { "type": "string" }, "agent_id": { "type": "string" }, "platform": { "type": "string", "enum": [ "android", "ios" ] }, "app_name": { "type": "string" }, "app_identifier": { "description": "Android package name or iOS bundle id", "type": "string", "example": "com.example.shop" }, "ios_team_id": { "type": [ "string", "null" ] }, "android_sha256_fingerprint": { "type": [ "string", "null" ] }, "store_url": { "type": [ "string", "null" ] } }, "type": "object" }, "AppPlatformInput": { "properties": { "agent_id": { "description": "Required on creation", "type": "string" }, "platform": { "description": "Required on creation, cannot change", "type": "string", "enum": [ "android", "ios" ] }, "app_name": { "description": "Required on creation", "type": "string", "maxLength": 255 }, "app_identifier": { "description": "Required on creation", "type": "string", "maxLength": 255 }, "ios_team_id": { "description": "Required for iOS", "type": "string", "maxLength": 50 }, "android_sha256_fingerprint": { "description": "Required for Android", "type": "string", "maxLength": 255 } }, "type": "object" }, "DeepLinkClick": { "properties": { "device": { "type": [ "string", "null" ] }, "os_version": { "type": [ "string", "null" ] }, "browser": { "type": [ "string", "null" ] }, "referrer": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "clicked_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "FollowUp": { "description": "A follow-up on a conversation: messages sent to the contact until they reply, or until the maximum of the type is reached.", "properties": { "id": { "description": "Public representation of follow-ups and their types (API v2.0)", "type": "string", "example": "FUP-XXXXX" }, "status": { "description": "`scheduled`: follow-ups still to send. `resolved`: the customer replied or someone closed it as done. `exhausted`: every follow-up was sent without a reply. `cancelled`. `failed`: the channel refused the sends.", "type": "string", "enum": [ "scheduled", "resolved", "exhausted", "cancelled", "failed" ] }, "type": { "properties": { "id": { "type": "string", "example": "FUI-XXXXX" }, "name": { "type": "string" } }, "type": "object" }, "conversation_id": { "type": "string" }, "channel": { "type": "string", "example": "whatsapp" }, "contact": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "identifier": { "description": "Phone number or email address", "type": "string" } }, "type": "object" }, "campaign_id": { "type": [ "string", "null" ] }, "reason": { "description": "What is expected from the contact; the AI writes the follow-ups from it", "type": "string" }, "message": { "description": "Fixed text sent instead of the AI-written one", "type": [ "string", "null" ] }, "set_by": { "type": "string", "enum": [ "ai", "agent", "api" ] }, "scheduled_at": { "description": "Next follow-up, while scheduled", "type": [ "string", "null" ], "format": "date-time" }, "sent": { "description": "Follow-ups sent so far", "type": "integer" }, "max_follow_ups": { "type": "integer" }, "last_sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "failed": { "description": "Sends the channel refused (not counted in `sent`)", "type": "integer" }, "last_error": { "type": [ "string", "null" ] }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "closed_by": { "type": [ "string", "null" ], "enum": [ "customer_replied", "agent", "ai", "api", "max_followups_reached", "expired", "cancelled", "send_failed" ] }, "note": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "FollowUpInput": { "required": [ "conversation_id", "type_id", "reason" ], "properties": { "conversation_id": { "description": "The conversation to follow up (GET /conversations)", "type": "string" }, "type_id": { "description": "GET /follow-up-types", "type": "string", "example": "FUI-XXXXX" }, "reason": { "description": "What is expected from the contact; the AI writes each follow-up from it", "type": "string", "maxLength": 2000 }, "message": { "description": "Fixed text to send instead of the AI-written one", "type": [ "string", "null" ], "maxLength": 4096 }, "scheduled_at": { "description": "First follow-up; by default after the delay of the type", "type": [ "string", "null" ], "format": "date-time" }, "campaign_id": { "description": "The campaign the follow-up belongs to", "type": [ "string", "null" ] } }, "type": "object" }, "FollowUpType": { "properties": { "id": { "type": "string", "example": "FUI-XXXXX" }, "name": { "type": "string" }, "slug": { "type": "string", "example": "payment_follow_up" }, "description": { "description": "Tells the AI when to set this type", "type": [ "string", "null" ] }, "color": { "type": [ "string", "null" ] }, "delay_minutes": { "description": "Before the first follow-up", "type": "integer" }, "interval_minutes": { "description": "Between two follow-ups", "type": "integer" }, "max_follow_ups": { "type": "integer" }, "active": { "type": "boolean" }, "overrides": { "description": "Settings for one sender, over the type's own", "type": "array", "items": { "$ref": "#/components/schemas/FollowUpTypeOverride" } }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "FollowUpTypeOverride": { "properties": { "channel_id": { "description": "The sender: WhatsApp phone number id or mailbox id (GET /channels)", "type": "string" }, "delay_minutes": { "type": [ "integer", "null" ] }, "interval_minutes": { "type": [ "integer", "null" ] }, "max_follow_ups": { "type": [ "integer", "null" ] } }, "type": "object" }, "FollowUpTypeInput": { "description": "On update, only the fields given change; `overrides`, when given, replaces them all.", "properties": { "name": { "description": "Required on creation", "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "color": { "type": [ "string", "null" ], "example": "#22c55e" }, "delay_minutes": { "type": "integer", "minimum": 1, "example": 60 }, "interval_minutes": { "type": "integer", "minimum": 1, "example": 1440 }, "max_follow_ups": { "type": "integer", "maximum": 10, "minimum": 1, "example": 2 }, "active": { "type": "boolean" }, "overrides": { "type": "array", "items": { "$ref": "#/components/schemas/FollowUpTypeOverride" } } }, "type": "object" }, "KnowledgeDocument": { "properties": { "id": { "description": "Public representation of the knowledge of an agent (API v2.0): its documents and what it knows about contacts", "type": "string", "example": "KNB-XXXXX" }, "title": { "type": "string" }, "excerpt": { "description": "First 200 characters", "type": "string" }, "content": { "description": "Markdown; only when one document is read (`GET /agents/{agent}/knowledge/{id}`)", "type": "string" }, "characters": { "description": "Counted in the limit of the plan", "type": "integer" }, "source": { "description": "`pdf` when the text comes from an uploaded PDF", "type": "string", "enum": [ "text", "pdf" ] }, "file_url": { "description": "The uploaded PDF", "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "KnowledgeDocumentInput": { "description": "JSON, or multipart/form-data to upload a PDF", "properties": { "title": { "description": "Required unless a PDF gives one", "type": "string", "maxLength": 255 }, "content": { "description": "Markdown; required unless a PDF is sent", "type": "string" }, "file": { "description": "PDF (10 MB max): its text becomes the content when none is sent", "type": "string", "format": "binary" } }, "type": "object" }, "KnowledgeUsage": { "properties": { "used": { "description": "Characters of all the documents of the agent", "type": "integer" }, "limit": { "description": "Set by the plan", "type": "integer" }, "remaining": { "type": "integer" } }, "type": "object" }, "ContactKnowledge": { "properties": { "id": { "type": "string", "example": "MEM-XXXXX" }, "contact": { "properties": { "identifier": { "type": "string" }, "identifier_type": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "type": "object" }, "content": { "type": "string", "example": "Prefers to be called Mrs. Ndongo; VIP customer since 2023." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "Message": { "properties": { "id": { "description": "Public representation of a message (API v2.0): exactly the data of the message.* webhooks.", "type": "string", "example": "msg.XXXXX" }, "conversation_id": { "type": "string" }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "channel": { "type": "string", "enum": [ "whatsapp", "mail", "shortext", "telegram" ] }, "channel_id": { "type": "string" }, "contact": { "type": "object" }, "message": { "properties": { "id": { "description": "Id on the channel (your own id for Shortext)", "type": [ "string", "null" ] }, "type": { "type": "string", "example": "text" }, "content": { "type": "object", "example": { "text": "Hello" } } }, "type": "object" }, "status": { "type": "string" }, "source": { "description": "What sent the message", "type": "string", "enum": [ "contact", "user", "ai", "api", "campaign", "follow_up", "external", "system" ] }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "MessageInput": { "description": "Grammar of a message, the same on every endpoint and version", "required": [ "type", "content" ], "properties": { "type": { "type": "string", "enum": [ "text", "template", "interactive", "media", "location", "contact" ] }, "content": { "description": "`text`: `{ text }`. `template`: `{ template_name, language, body?, header?, buttons?, code? }` (body/header: `{ variable: value }`; buttons: `{ index: value }` for the buttons that need one, see GET /templates; code: the code of an authentication template). `interactive`: `{ type, body, action, header?, footer? }`. `media`: `{ media_type, media_url, caption?, filename?, mime? }` (media_type: image, video, document, audio, sticker; a sticker is a WebP image, 512x512, 100 KB at most or 500 KB animated, without caption). `location`: `{ latitude, longitude, name?, address? }` (with a name and an address, the place shows as a card). `contact`: `{ firstname, lastname?, phones: [{ number, type? }] }` (1 to 5 numbers, type: cell, main, iphone, home, work). On email, a location or a contact is sent as text: name, address and map link, or name and numbers", "type": "object", "example": { "text": "Hello, how can I help?" } } }, "type": "object" }, "ReplyInput": { "required": [ "message" ], "properties": { "message": { "$ref": "#/components/schemas/MessageInput" }, "handover": { "description": "The reply takes the conversation over: the AI agent stops answering. Send false for a notification that lets the agent continue.", "type": "boolean", "default": true } }, "type": "object" }, "Template": { "properties": { "id": { "description": "Public representation of a WhatsApp template (API v2.0). A template belongs to a WhatsApp Business\nAccount: every number of that account can send it (`channels`).", "type": "string" }, "name": { "description": "message.content.template_name", "type": "string", "example": "order_update" }, "language": { "description": "message.content.language", "type": "string", "example": "fr" }, "status": { "description": "Only APPROVED templates can be sent", "type": "string", "enum": [ "APPROVED", "PENDING", "REJECTED" ] }, "rejection_reason": { "type": [ "string", "null" ] }, "quality": { "type": [ "string", "null" ], "example": "GREEN" }, "category": { "type": [ "string", "null" ], "example": "UTILITY" }, "channels": { "description": "WhatsApp channel ids (channel_id) of the company that can send it", "type": "array", "items": { "type": "string" } }, "header": { "properties": { "type": { "type": "string", "enum": [ "NONE", "TEXT", "IMAGE", "VIDEO", "DOCUMENT" ] }, "text": { "type": [ "string", "null" ] }, "variables": { "description": "TEXT header: `message.content.header` = `{ name: value }`", "type": "array", "items": { "type": "string" } }, "media_url": { "description": "Media header: sent when message.content.header.url is not given", "type": [ "string", "null" ] } }, "type": "object" }, "body": { "properties": { "text": { "type": "string", "example": "Hello {{name}}, your order {{order}} is ready." }, "variables": { "description": "`message.content.body` = `{ name: value }`", "type": "array", "items": { "type": "string" }, "example": [ "name", "order" ] } }, "type": "object" }, "footer": { "type": [ "string", "null" ] }, "buttons": { "description": "In order: `message.content.buttons` = `{ index: value }` for the buttons that need a value", "type": "array", "items": { "properties": { "index": { "type": "integer", "example": 0 }, "type": { "type": "string", "enum": [ "QUICK_REPLY", "URL", "PHONE_NUMBER", "COPY_CODE", "OTP" ], "example": "URL" }, "text": { "type": [ "string", "null" ] }, "needs_value": { "description": "A dynamic link (its end), a copy code button (the coupon) or the code of an authentication template (or send `message.content.code`)", "type": "boolean" } }, "type": "object" } }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "Ticket": { "properties": { "id": { "description": "Public representation of tickets, their statuses, priorities and activity (API v2.0)", "type": "string", "example": "STT-XXXXX" }, "subject": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/TicketStatus" }, "priority": { "oneOf": [ { "$ref": "#/components/schemas/SlaPolicy" }, { "type": "null" } ] }, "agent": { "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "conversation_id": { "description": "Conversation of the contact the ticket is about", "type": [ "string", "null" ] }, "contact": { "description": "Same block as in a Conversation", "type": [ "object", "null" ] }, "response_due_at": { "description": "Set by the priority (SLA)", "type": [ "string", "null" ], "format": "date-time" }, "resolve_due_at": { "description": "Set by the priority (SLA)", "type": [ "string", "null" ], "format": "date-time" }, "responded_at": { "type": [ "string", "null" ], "format": "date-time" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "response_breached": { "description": "Answered after response_due_at", "type": "boolean" }, "resolve_breached": { "description": "Resolved after resolve_due_at", "type": "boolean" }, "satisfaction_rating": { "type": [ "integer", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "TicketInput": { "properties": { "conversation_id": { "description": "Required on creation: the ticket follows the contact of this conversation and the agent of its channel", "type": "string" }, "subject": { "description": "Required on creation", "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 10000 }, "status": { "description": "Status code of the agent; on creation, its first open status by default. A resolved or terminal status resolves or closes the ticket, an open one reopens it.", "type": "string", "example": "in_progress" }, "priority": { "description": "SLA policy code of the agent: sets the due dates; null removes it", "type": [ "string", "null" ], "example": "high" } }, "type": "object" }, "TicketStatus": { "properties": { "code": { "description": "Slug of the name: what tickets refer to", "type": "string", "example": "in_progress" }, "name": { "type": "string", "example": "In progress" }, "position": { "description": "Order on the tickets board", "type": "integer" }, "active": { "type": "boolean" }, "resolved": { "description": "Tickets moved here are resolved", "type": "boolean" }, "terminal": { "description": "Tickets moved here are closed", "type": "boolean" }, "pending": { "description": "Waiting on the customer or a third party: the status « Put on hold » moves tickets to", "type": "boolean" } }, "type": "object" }, "TicketStatusInput": { "properties": { "name": { "description": "Required on creation; renaming changes the code", "type": "string", "maxLength": 255 }, "position": { "type": "integer", "minimum": 0 }, "active": { "type": "boolean", "default": true }, "resolved": { "type": "boolean", "default": false }, "terminal": { "type": "boolean", "default": false }, "pending": { "type": "boolean", "default": false } }, "type": "object" }, "SlaPolicy": { "properties": { "priority": { "description": "Slug of the label: what tickets refer to", "type": "string", "example": "high" }, "label": { "type": "string", "example": "High" }, "response_time": { "description": "Working minutes to answer (Monday to Friday, 8:00 to 18:00)", "type": "integer", "example": 60 }, "resolve_time": { "description": "Working minutes to resolve", "type": "integer", "example": 480 } }, "type": "object" }, "SlaPolicyInput": { "properties": { "label": { "description": "Required on creation; renaming changes the priority code", "type": "string", "maxLength": 255 }, "response_time": { "description": "Required on creation, working minutes", "type": "integer", "minimum": 1 }, "resolve_time": { "description": "Required on creation, working minutes", "type": "integer", "minimum": 1 } }, "type": "object" }, "TicketActivity": { "properties": { "id": { "type": "string", "example": "TLA-XXXXX" }, "type": { "type": "string", "enum": [ "ticket_created", "status_changed", "ticket_resolved", "ticket_closed", "ticket_reopened", "comment", "response", "response_time_breached", "resolve_time_breached" ] }, "text": { "description": "The note or the answer", "type": [ "string", "null" ] }, "sent_to_contact": { "description": "An answer the contact received", "type": "boolean" }, "author": { "description": "Member, AI agent or ` (API)`", "type": [ "string", "null" ] }, "from_status": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "ApiEnvelope": { "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "example": 1000 }, "message": { "type": "string", "example": "Request success." }, "body": { "description": "Endpoint payload, null when there is none" }, "token": { "description": "Present only on authentication routes", "type": [ "string", "null" ] }, "trace_id": { "description": "Present only when success is false", "type": [ "string", "null" ] } }, "type": "object" }, "ApiPage": { "description": "A page of results: `data` holds the items. Ask another page with `?page=`", "properties": { "current_page": { "type": "integer", "example": 1 }, "data": { "type": "array", "items": {} }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 120 }, "last_page": { "type": "integer", "example": 3 }, "from": { "type": [ "integer", "null" ] }, "to": { "type": [ "integer", "null" ] }, "first_page_url": { "type": "string" }, "last_page_url": { "type": "string" }, "next_page_url": { "type": [ "string", "null" ] }, "prev_page_url": { "type": [ "string", "null" ] }, "path": { "type": "string" } }, "type": "object" }, "HostedSession": { "description": "A signed, expiring, single-use link to one of our hosted pages, and its outcome", "properties": { "id": { "description": "Session id", "type": "string", "format": "uuid" }, "purpose": { "type": "string", "example": "whatsapp" }, "status": { "type": "string", "enum": [ "pending", "opened", "completed", "failed", "cancelled", "expired" ] }, "url": { "description": "Only in the creation response: the page to give to your user. It holds a secret, never log or share it.", "type": "string" }, "context": { "type": "object" }, "result": { "description": "What the session produced (completed)", "type": [ "object", "null" ] }, "error": { "type": [ "string", "null" ] }, "return_url": { "description": "Your page the user is sent back to, with ?session_id=...&status=...", "type": [ "string", "null" ] }, "locale": { "type": [ "string", "null" ] }, "expires_at": { "type": "string", "format": "date-time" }, "opened_at": { "type": [ "string", "null" ], "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "HostedSessionInput": { "required": [ "purpose" ], "properties": { "purpose": { "description": "GET /hosted-sessions/purposes", "type": "string", "example": "whatsapp" }, "context": { "description": "Options of the purpose", "type": "object" }, "return_url": { "type": [ "string", "null" ], "format": "uri" }, "locale": { "type": [ "string", "null" ], "example": "fr" }, "expires_in": { "description": "Minutes, default 60", "type": "integer", "maximum": 1440, "minimum": 5 } }, "type": "object" }, "WebhookEndpointInput": { "properties": { "url": { "description": "Public HTTPS URL", "type": "string", "format": "uri", "example": "https://example.com/webhooks/shortext" }, "events": { "type": "array", "items": { "type": "string" }, "example": [ "message.*", "conversation.handover" ] }, "filters": { "description": "Only receive events whose context matches, e.g. one agent", "type": [ "object", "null" ], "example": { "app": "AGI-XXXXX" } }, "description": { "type": [ "string", "null" ] }, "is_enabled": { "type": "boolean" } }, "type": "object" }, "WebhookEndpoint": { "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "filters": { "type": [ "object", "null" ] }, "api_version": { "description": "Version of the payloads sent to this endpoint", "type": [ "string", "null" ], "example": "v2.0" }, "description": { "type": [ "string", "null" ] }, "is_enabled": { "type": "boolean" }, "disabled_reason": { "description": "Set when disabled after failing for 3 days", "type": [ "string", "null" ] }, "failing_since": { "type": [ "string", "null" ], "format": "date-time" }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_failure_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_error": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "WebhookDelivery": { "properties": { "id": { "description": "Sent in the Delivery header", "type": "string", "format": "uuid" }, "event_id": { "type": "string", "example": "evt_01JB..." }, "event_type": { "type": "string", "example": "message.received" }, "status": { "type": "string", "enum": [ "pending", "succeeded", "failed" ] }, "attempts": { "type": "integer" }, "response_status": { "type": [ "integer", "null" ] }, "response_body": { "description": "First 2000 characters", "type": [ "string", "null" ] }, "duration_ms": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "next_retry_at": { "type": [ "string", "null" ], "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "payload": { "$ref": "#/components/schemas/WebhookEventPayload" } }, "type": "object" }, "WebhookEventPayload": { "description": "Body POSTed to your endpoint. Answer with a 2xx within 10 s and process asynchronously.\nFailed deliveries are retried after 10 s, 1 min, 5 min, 30 min, 2 h, 6 h and 12 h;\nan endpoint failing for 3 days is disabled.\nDelivery order is not guaranteed and an event may be delivered twice: dedupe on `id`.\n\n**Signature**: `X-…-Signature: sha256=hex(hmac_sha256(secret, \"{X-…-Timestamp}.{raw body}\"))`.\nCompare in constant time and reject timestamps older than 5 minutes.", "properties": { "id": { "description": "Event id, identical on redeliveries", "type": "string", "example": "evt_01JB..." }, "type": { "type": "string", "example": "message.received" }, "api_version": { "type": [ "string", "null" ], "example": "v2.0" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "description": "Depends on the event type", "type": "object" } }, "type": "object" } }, "securitySchemes": { "bearerAuth": { "type": "http", "description": "Company API key, sent as `Authorization: Bearer `. Create it in the dashboard (Developer > API Keys) with the permissions the integration needs.", "scheme": "bearer" } } }, "tags": [ { "name": "Agents", "description": "Agents" }, { "name": "Knowledge", "description": "Knowledge" }, { "name": "Dynamic links", "description": "Dynamic links" }, { "name": "Billing", "description": "Billing" }, { "name": "Campaigns", "description": "Campaigns" }, { "name": "Channels", "description": "Channels" }, { "name": "Conversations", "description": "Conversations" }, { "name": "Follow-ups", "description": "Follow-ups" }, { "name": "Account", "description": "Account" }, { "name": "Tickets", "description": "Tickets" }, { "name": "Templates", "description": "Templates" }, { "name": "Hosted sessions", "description": "Hosted sessions" }, { "name": "Webhooks", "description": "Webhooks" } ] }