{ "openapi": "3.0.3", "info": { "title": "Linkatudo Hub Public API", "version": "1.0.0", "description": "Public contract for channel discovery and canonical provider-agnostic message delivery." }, "servers": [{ "url": "/api/v1" }], "paths": { "/accounts/{accountId}/channels": { "get": { "operationId": "listChannels", "summary": "List registered account channels", "description": "Returns all non-deleted channels registered for the account across supported providers.", "security": [{ "ApiKeyAuth": [] }], "parameters": [ { "$ref": "#/components/parameters/accountId" } ], "responses": { "200": { "description": "Registered account channels", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Channel" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/accounts/{accountId}/channels/{channelId}/messages": { "post": { "operationId": "sendMessage", "summary": "Send messages through an account channel", "description": "Permanently accepts eligible messages asynchronously. Meta channels resolve typed Contact identities and enforce the Contact inbound window. Active matching idempotent replays remain accepted without re-evaluating that window.", "security": [{ "ApiKeyAuth": [] }], "parameters": [ { "$ref": "#/components/parameters/accountId" }, { "name": "channelId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 128 } }, { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageRequest" }, "examples": { "text": { "value": { "to": "5511988887777", "contents": [{ "type": "text", "text": "Hello" }] } }, "image": { "value": { "to": "5511988887777", "contents": [{ "type": "file", "fileMimeType": "image", "fileUrl": "https://cdn.example.com/image.jpg" }] } } } } } }, "responses": { "202": { "description": "Message accepted or replayed for durable asynchronous delivery", "headers": { "Location": { "required": true, "schema": { "type": "string" } }, "Idempotency-Key": { "required": true, "description": "Effective supplied or generated UUID", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryAcceptance" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/MessageTargetNotFound" }, "413": { "$ref": "#/components/responses/BodyTooLarge" }, "415": { "$ref": "#/components/responses/ContentTypeInvalid" }, "422": { "$ref": "#/components/responses/UnsupportedContent" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "409": { "$ref": "#/components/responses/MessageConflict" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/accounts/{accountId}/channels/{channelId}/templates": { "get": { "operationId": "listWhatsAppTemplates", "summary": "List approved WhatsApp templates", "description": "Lists bounded templates for one active WhatsApp Cloud or Coexistence channel. The opaque cursor is account- and WABA-scoped and must not be treated as a URL.", "security": [{ "ApiKeyAuth": [] }], "parameters": [ { "$ref": "#/components/parameters/accountId" }, { "name": "channelId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 128 } }, { "$ref": "#/components/parameters/templateAfter" } ], "responses": { "200": { "description": "Normalized template page", "headers": { "Cache-Control": { "required": true, "schema": { "type": "string", "enum": ["no-store"] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplatePage" } } } }, "400": { "$ref": "#/components/responses/TemplateBadRequest" }, "401": { "$ref": "#/components/responses/TemplateUnauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/TemplateChannelNotFound" }, "422": { "$ref": "#/components/responses/TemplatesNotSupported" }, "502": { "$ref": "#/components/responses/ProviderRequestFailed" }, "503": { "$ref": "#/components/responses/TemplatesNotConfigured" } } } }, "/accounts/{accountId}/contacts/{contactId}": { "get": { "operationId": "getContact", "summary": "Get an account contact", "description": "Missing and foreign-account contact identifiers return the same response. contactAvatar is a short-lived signed private URL or null; provider URLs and storage metadata are never returned.", "security": [{ "ApiKeyAuth": [] }], "parameters": [ { "$ref": "#/components/parameters/accountId" }, { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 128 } } ], "responses": { "200": { "description": "Account contact", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/ContactNotFound" } } } }, "/accounts/{accountId}/message-deliveries/{requestId}": { "get": { "operationId": "getMessageDelivery", "summary": "Get asynchronous message delivery status", "security": [{ "ApiKeyAuth": [] }], "parameters": [ { "$ref": "#/components/parameters/accountId" }, { "name": "requestId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 128 } } ], "responses": { "200": { "description": "Current delivery status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryStatus" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-Api-Key" } }, "parameters": { "accountId": { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 128 } }, "idempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID. When omitted, the server generates and returns one. A supplied key is account-scoped and active for [acceptedAt, acceptedAt + 24 hours). Same-key retries after expiry create a new delivery. Retrying without a key after a lost response may duplicate delivery.", "schema": { "type": "string", "format": "uuid" } }, "templateAfter": { "name": "after", "in": "query", "required": false, "description": "Opaque non-empty Meta cursor, maximum 2,048 characters.", "schema": { "type": "string", "minLength": 1, "maxLength": 2048 } } }, "schemas": { "Channel": { "type": "object", "additionalProperties": false, "required": ["id", "name", "type", "externalId", "status", "iconUrl"], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": ["WHATSAPP_CLOUD", "WHATSAPP_COEXISTENCE", "WHATSAPP_EVO", "FACEBOOK", "INSTAGRAM", "TELEGRAM"] }, "externalId": { "type": "string" }, "status": { "type": "string", "enum": ["ACTIVE", "INACTIVE", "PENDING"] }, "iconUrl": { "type": "string", "format": "uri", "description": "Public absolute URL for the channel brand SVG icon." } } }, "Contact": { "type": "object", "additionalProperties": false, "required": ["id", "channelId", "identities", "contactName", "contactAvatar", "lastInboundAt"], "properties": { "id": { "type": "string" }, "channelId": { "type": "string" }, "identities": { "type": "array", "maxItems": 16, "items": { "$ref": "#/components/schemas/ContactIdentity" } }, "contactName": { "type": "string", "nullable": true }, "contactAvatar": { "type": "string", "format": "uri", "nullable": true, "description": "Short-lived signed private avatar URL, or null when no usable Attachment exists." }, "lastInboundAt": { "type": "string", "format": "date-time", "nullable": true } } }, "ContactIdentity": { "type": "object", "additionalProperties": false, "required": ["type", "value", "isPrimary"], "properties": { "type": { "type": "string", "enum": ["PHONE", "WA_ID", "BSUID", "PARENT_BSUID", "JID", "PSID", "IGSID", "CHAT_ID", "USER_ID", "USERNAME"] }, "value": { "type": "string", "minLength": 1, "maxLength": 256 }, "isPrimary": { "type": "boolean" } } }, "SendMessageRequest": { "type": "object", "additionalProperties": false, "required": ["contents"], "properties": { "to": { "type": "string", "minLength": 1, "maxLength": 256 }, "contactId": { "type": "string", "minLength": 1, "maxLength": 128 }, "conversationId": { "type": "string", "minLength": 1, "maxLength": 128 }, "contents": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "$ref": "#/components/schemas/Content" } }, "reply": { "type": "boolean" }, "messageId": { "type": "string", "maxLength": 512 } }, "oneOf": [ { "required": ["to"] }, { "required": ["contactId"] }, { "required": ["conversationId"] } ] }, "Content": { "oneOf": [ { "$ref": "#/components/schemas/TextContent" }, { "$ref": "#/components/schemas/FileContent" }, { "$ref": "#/components/schemas/StickerContent" }, { "$ref": "#/components/schemas/LocationContent" }, { "$ref": "#/components/schemas/ReactionContent" }, { "$ref": "#/components/schemas/InteractiveContent" }, { "$ref": "#/components/schemas/ContactContent" } ,{ "$ref": "#/components/schemas/TemplateContent" } ], "discriminator": { "propertyName": "type" } }, "TextContent": { "type": "object", "additionalProperties": false, "required": ["type", "text"], "properties": { "type": { "type": "string", "enum": ["text"] }, "text": { "type": "string", "minLength": 1, "maxLength": 4096 } } }, "FileContent": { "type": "object", "additionalProperties": false, "required": ["type", "fileMimeType"], "properties": { "type": { "type": "string", "enum": ["file"] }, "fileMimeType": { "type": "string", "enum": ["image", "video", "document", "audio"] }, "fileUrl": { "type": "string", "format": "uri", "maxLength": 2048 }, "mediaId": { "type": "string", "maxLength": 512 }, "fileName": { "type": "string", "maxLength": 255 }, "fileCaption": { "type": "string", "maxLength": 1024 } } }, "StickerContent": { "type": "object", "additionalProperties": false, "required": ["type"], "properties": { "type": { "type": "string", "enum": ["sticker"] }, "fileUrl": { "type": "string", "format": "uri", "maxLength": 2048 }, "mediaId": { "type": "string", "maxLength": 512 } } }, "LocationContent": { "type": "object", "additionalProperties": false, "required": ["type", "longitude", "latitude"], "properties": { "type": { "type": "string", "enum": ["location"] }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 }, "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "name": { "type": "string", "maxLength": 256 }, "address": { "type": "string", "maxLength": 512 } } }, "ReactionContent": { "type": "object", "additionalProperties": false, "required": ["type", "reaction"], "properties": { "type": { "type": "string", "enum": ["reaction"] }, "reaction": { "type": "object", "additionalProperties": false, "required": ["message_id", "emoji"], "properties": { "message_id": { "type": "string", "maxLength": 512 }, "emoji": { "type": "string", "maxLength": 32 } } } } }, "InteractiveContent": { "type": "object", "additionalProperties": false, "required": ["type", "interactive"], "properties": { "type": { "type": "string", "enum": ["interactive"] }, "interactive": { "type": "object" } } }, "ContactContent": { "type": "object", "additionalProperties": false, "required": ["type", "contacts"], "properties": { "type": { "type": "string", "enum": ["contact"] }, "contacts": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "object" } } } }, "TemplateContent": { "type": "object", "additionalProperties": false, "required": ["type", "template"], "description": "One complete Meta template is the only content allowed in this request. Template media accepts only a Meta media ID. The ID is retained only in server-side message content through normal message retention for asynchronous retries and is never returned in delivery status, template listings, tenant relays, operational events, or safe chat DTOs. Nested media links are invalid.", "properties": { "type": { "type": "string", "enum": ["template"] }, "template": { "type": "object", "additionalProperties": false, "required": ["name", "language"], "properties": { "name": { "type": "string", "pattern": "^[a-z0-9_]{1,512}$" }, "language": { "type": "object", "additionalProperties": false, "required": ["code"], "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,35}$" } } }, "components": { "type": "array", "maxItems": 12, "items": { "$ref": "#/components/schemas/TemplateComponent" } } } } }, "examples": { "parameterless": { "value": { "type": "template", "template": { "name": "order_confirmation", "language": { "code": "pt_BR" } } } }, "bodyParameter": { "value": { "type": "template", "template": { "name": "appointment_reminder", "language": { "code": "en_US" }, "components": [{ "type": "body", "parameters": [{ "type": "text", "text": "Maria" }] }] } } }, "buttonParameter": { "value": { "type": "template", "template": { "name": "confirm_order", "language": { "code": "pt_BR" }, "components": [{ "type": "button", "sub_type": "quick_reply", "index": "0", "parameters": [{ "type": "payload", "payload": "confirm" }] }] } } }, "mediaIdHeader": { "summary": "Meta media ID retained only through normal async message retention", "description": "Use a bounded Meta media ID, not link. Server retains it only inside message content until normal retention for retries and never discloses it through status, listing, relay, events, or safe chat DTOs.", "value": { "type": "template", "template": { "name": "invoice_ready", "language": { "code": "en_US" }, "components": [{ "type": "header", "parameters": [{ "type": "document", "document": { "id": "meta-media-id-placeholder" } }] }] } } } } }, "TemplateComponent": { "oneOf": [ { "$ref": "#/components/schemas/TemplateHeaderComponent" }, { "$ref": "#/components/schemas/TemplateBodyComponent" }, { "$ref": "#/components/schemas/TemplateButtonComponent" } ], "discriminator": { "propertyName": "type" } }, "TemplateHeaderComponent": { "type": "object", "additionalProperties": false, "required": ["type", "parameters"], "properties": { "type": { "type": "string", "enum": ["header"] }, "parameters": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/TemplateHeaderParameter" } } } }, "TemplateHeaderParameter": { "oneOf": [ { "$ref": "#/components/schemas/TemplateTextParameter" }, { "type": "object", "additionalProperties": false, "required": ["type", "image"], "properties": { "type": { "type": "string", "enum": ["image"] }, "image": { "$ref": "#/components/schemas/TemplateMediaId" } } }, { "type": "object", "additionalProperties": false, "required": ["type", "video"], "properties": { "type": { "type": "string", "enum": ["video"] }, "video": { "$ref": "#/components/schemas/TemplateMediaId" } } }, { "type": "object", "additionalProperties": false, "required": ["type", "document"], "properties": { "type": { "type": "string", "enum": ["document"] }, "document": { "$ref": "#/components/schemas/TemplateMediaId" } } } ] }, "TemplateMediaId": { "type": "object", "additionalProperties": false, "required": ["id"], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Meta media ID only; nested links are invalid and this value is never returned by public status, listing, relay, events, or safe chat DTOs." } } }, "TemplateBodyComponent": { "type": "object", "additionalProperties": false, "required": ["type", "parameters"], "properties": { "type": { "type": "string", "enum": ["body"] }, "parameters": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/TemplateBodyParameter" } } } }, "TemplateBodyParameter": { "oneOf": [ { "$ref": "#/components/schemas/TemplateTextParameter" }, { "type": "object", "additionalProperties": false, "required": ["type", "currency"], "properties": { "type": { "type": "string", "enum": ["currency"] }, "currency": { "type": "object", "additionalProperties": false, "required": ["fallback_value", "code", "amount_1000"], "properties": { "fallback_value": { "type": "string", "minLength": 1, "maxLength": 256 }, "code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "amount_1000": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } } } }, { "type": "object", "additionalProperties": false, "required": ["type", "date_time"], "properties": { "type": { "type": "string", "enum": ["date_time"] }, "date_time": { "type": "object", "additionalProperties": false, "required": ["fallback_value"], "properties": { "fallback_value": { "type": "string", "minLength": 1, "maxLength": 256 } } } } } ] }, "TemplateTextParameter": { "type": "object", "additionalProperties": false, "required": ["type", "text"], "properties": { "type": { "type": "string", "enum": ["text"] }, "text": { "type": "string", "minLength": 1, "maxLength": 4096 } } }, "TemplateButtonComponent": { "description": "The parameter type is coupled to sub_type: url uses text, quick_reply uses payload, and copy_code uses coupon_code.", "oneOf": [ { "$ref": "#/components/schemas/TemplateUrlButtonComponent" }, { "$ref": "#/components/schemas/TemplateQuickReplyButtonComponent" }, { "$ref": "#/components/schemas/TemplateCopyCodeButtonComponent" } ] }, "TemplateUrlButtonComponent": { "type": "object", "additionalProperties": false, "required": ["type", "sub_type", "index", "parameters"], "properties": { "type": { "type": "string", "enum": ["button"] }, "sub_type": { "type": "string", "enum": ["url"] }, "index": { "type": "string", "pattern": "^[0-9]$" }, "parameters": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/TemplateTextParameter" } } } }, "TemplateQuickReplyButtonComponent": { "type": "object", "additionalProperties": false, "required": ["type", "sub_type", "index", "parameters"], "properties": { "type": { "type": "string", "enum": ["button"] }, "sub_type": { "type": "string", "enum": ["quick_reply"] }, "index": { "type": "string", "pattern": "^[0-9]$" }, "parameters": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "additionalProperties": false, "required": ["type", "payload"], "properties": { "type": { "type": "string", "enum": ["payload"] }, "payload": { "type": "string", "minLength": 1, "maxLength": 256 } } } } } }, "TemplateCopyCodeButtonComponent": { "type": "object", "additionalProperties": false, "required": ["type", "sub_type", "index", "parameters"], "properties": { "type": { "type": "string", "enum": ["button"] }, "sub_type": { "type": "string", "enum": ["copy_code"] }, "index": { "type": "string", "pattern": "^[0-9]$" }, "parameters": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "additionalProperties": false, "required": ["type", "coupon_code"], "properties": { "type": { "type": "string", "enum": ["coupon_code"] }, "coupon_code": { "type": "string", "minLength": 1, "maxLength": 256 } } } } } }, "TemplateButtonParameter": { "oneOf": [ { "$ref": "#/components/schemas/TemplateTextParameter" }, { "$ref": "#/components/schemas/TemplatePayloadParameter" }, { "$ref": "#/components/schemas/TemplateCouponCodeParameter" } ] }, "TemplatePayloadParameter": { "type": "object", "additionalProperties": false, "required": ["type", "payload"], "properties": { "type": { "type": "string", "enum": ["payload"] }, "payload": { "type": "string", "minLength": 1, "maxLength": 256 } } }, "TemplateCouponCodeParameter": { "type": "object", "additionalProperties": false, "required": ["type", "coupon_code"], "properties": { "type": { "type": "string", "enum": ["coupon_code"] }, "coupon_code": { "type": "string", "minLength": 1, "maxLength": 256 } } }, "TemplatePage": { "type": "object", "additionalProperties": false, "required": ["data", "nextCursor"], "properties": { "data": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/TemplateListItem" } }, "nextCursor": { "type": "string", "maxLength": 2048, "nullable": true } } }, "TemplateListItem": { "type": "object", "additionalProperties": false, "required": ["name", "language", "status", "category", "components"], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 512 }, "language": { "type": "string", "minLength": 1, "maxLength": 35 }, "status": { "type": "string", "minLength": 1, "maxLength": 64 }, "category": { "type": "string", "minLength": 1, "maxLength": 64 }, "components": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/TemplateListComponent" } } } }, "TemplateListComponent": { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "maxLength": 64 }, "format": { "type": "string", "maxLength": 64 }, "text": { "type": "string", "maxLength": 4096 }, "example": { "type": "object", "additionalProperties": false, "properties": { "bodyText": { "type": "array", "maxItems": 5, "items": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 4096 } } }, "headerText": { "type": "array", "maxItems": 5, "items": { "type": "string", "maxLength": 4096 } }, "button": { "type": "array", "maxItems": 10, "items": { "type": "string", "maxLength": 256 } } } }, "buttons": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/TemplateListButton" } } } }, "TemplateListButton": { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "maxLength": 64 }, "text": { "type": "string", "maxLength": 256 }, "url": { "type": "string", "maxLength": 2048 }, "phoneNumber": { "type": "string", "maxLength": 64 }, "example": { "type": "array", "maxItems": 10, "items": { "type": "string", "maxLength": 256 } } } }, "DeliveryAcceptance": { "type": "object", "additionalProperties": false, "required": ["requestId"], "properties": { "requestId": { "type": "string" } } }, "DeliveryStatus": { "type": "object", "additionalProperties": false, "required": ["requestId", "status", "createdAt", "acceptedAt", "expiresAt", "attemptCount", "jobs"], "properties": { "requestId": { "type": "string" }, "status": { "type": "string", "enum": ["PENDING", "PROCESSING", "DELIVERED", "PARTIALLY_DELIVERED", "FAILED", "UNKNOWN", "EXPIRED", "CANCELLED"] }, "createdAt": { "type": "string", "format": "date-time" }, "acceptedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true }, "attemptCount": { "type": "integer", "minimum": 0 }, "lastAttemptAt": { "type": "string", "format": "date-time", "nullable": true }, "jobs": { "type": "array", "items": { "$ref": "#/components/schemas/DeliveryJobStatus" } } } }, "DeliveryJobStatus": { "type": "object", "additionalProperties": false, "required": ["jobId", "position", "status", "attemptCount"], "properties": { "jobId": { "type": "string" }, "position": { "type": "integer", "nullable": true }, "status": { "type": "string", "enum": ["PENDING", "PROCESSING", "RETRY_WAIT", "SENT", "FAILED", "UNKNOWN", "EXPIRED", "CANCELLED"] }, "attemptCount": { "type": "integer", "minimum": 0 }, "lastErrorCode": { "type": "string", "nullable": true }, "messageId": { "type": "string", "nullable": true }, "providerMessageId": { "type": "string", "nullable": true }, "messageStatus": { "type": "string", "nullable": true } } }, "ErrorResponse": { "type": "object", "additionalProperties": false, "required": ["error"], "properties": { "error": { "type": "string" } } }, "ForbiddenErrorResponse": { "type": "object", "additionalProperties": false, "required": ["error"], "properties": { "error": { "type": "string", "enum": ["ACCOUNT_UNAVAILABLE"] } } }, "TooManyRequestsErrorResponse": { "type": "object", "additionalProperties": false, "required": ["error"], "properties": { "error": { "type": "string", "enum": ["RATE_LIMITED", "OUTBOUND_MESSAGE_LIMIT_REACHED"] } } }, "BadRequestErrorResponse": { "type": "object", "additionalProperties": false, "required": ["error"], "properties": { "error": { "type": "string", "enum": ["REQUEST_INVALID", "IDEMPOTENCY_KEY_INVALID", "PERSIST_FALSE_NOT_SUPPORTED"] } } }, "ConflictErrorResponse": { "type": "object", "additionalProperties": false, "required": ["error"], "properties": { "error": { "type": "string", "enum": ["IDEMPOTENCY_KEY_REUSED", "WINDOW_CLOSED"] } } }, "ServiceUnavailableErrorResponse": { "type": "object", "additionalProperties": false, "required": ["error"], "properties": { "error": { "type": "string", "enum": ["MEDIA_UNAVAILABLE", "DELIVERY_IDEMPOTENCY_UNAVAILABLE", "SERVICE_UNAVAILABLE"] } } }, "ContactNotFoundErrorResponse": { "type": "object", "additionalProperties": false, "required": ["error"], "properties": { "error": { "type": "string", "enum": ["CONTACT_NOT_FOUND"] } } }, "MessageTargetNotFoundErrorResponse": { "type": "object", "additionalProperties": false, "required": ["error"], "properties": { "error": { "type": "string", "enum": ["CHANNEL_NOT_FOUND", "CONTACT_NOT_FOUND"] } } }, "TemplateListErrorResponse": { "type": "object", "additionalProperties": false, "required": ["error"], "properties": { "error": { "type": "string", "enum": ["REQUEST_INVALID", "UNAUTHORIZED", "ACCOUNT_UNAVAILABLE", "CHANNEL_NOT_FOUND", "TEMPLATES_NOT_SUPPORTED", "TEMPLATES_NOT_CONFIGURED", "PROVIDER_REQUEST_FAILED"] } } }, "TemplateUnauthorizedErrorResponse": { "type": "object", "additionalProperties": false, "required": ["error"], "properties": { "error": { "type": "string", "enum": ["UNAUTHORIZED"] } } } }, "responses": { "BadRequest": { "description": "Malformed request or malformed supplied idempotency UUID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponse" } } } }, "Unauthorized": { "description": "API key missing, invalid, or not bound to the account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Forbidden": { "description": "Account is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenErrorResponse" }, "examples": { "accountUnavailable": { "value": { "error": "ACCOUNT_UNAVAILABLE" } } } } } }, "NotFound": { "description": "Active account-bound channel not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "MessageTargetNotFound": { "description": "Active account-bound channel or account-scoped Contact not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageTargetNotFoundErrorResponse" }, "examples": { "channelNotFound": { "value": { "error": "CHANNEL_NOT_FOUND" } }, "contactNotFound": { "value": { "error": "CONTACT_NOT_FOUND" } } } } } }, "ContactNotFound": { "description": "Contact is missing, belongs to another account, or is not owned by an active channel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactNotFoundErrorResponse" }, "example": { "error": "CONTACT_NOT_FOUND" } } } }, "BodyTooLarge": { "description": "Request body exceeds the configured limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ContentTypeInvalid": { "description": "Content-Type must be application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "UnsupportedContent": { "description": "Content is unsupported by the selected provider", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "TooManyRequests": { "description": "Per-key or per-account rate limit or monthly outbound-message limit exceeded", "headers": { "Retry-After": { "description": "Present for retryable request rate limits", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsErrorResponse" }, "examples": { "rateLimited": { "value": { "error": "RATE_LIMITED" } }, "outboundLimitReached": { "value": { "error": "OUTBOUND_MESSAGE_LIMIT_REACHED" } } } } } }, "Conflict": { "description": "Active idempotency key reused with different canonical content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictErrorResponse" } } } }, "MessageConflict": { "description": "Active idempotency key conflict or closed Meta conversation window", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictErrorResponse" }, "examples": { "windowClosed": { "value": { "error": "WINDOW_CLOSED" } } } } } }, "ServiceUnavailable": { "description": "Async delivery, private media storage, safe idempotency comparison, or required public icon URL configuration is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableErrorResponse" } } } } ,"TemplateBadRequest": { "description": "Cursor is missing, empty, duplicated, or exceeds 2,048 characters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateListErrorResponse" }, "example": { "error": "REQUEST_INVALID" } } } }, "TemplateUnauthorized": { "description": "API key missing, invalid, or not bound to the account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateUnauthorizedErrorResponse" } } } }, "TemplateChannelNotFound": { "description": "Channel is missing, foreign, deleted, inactive, or pending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateListErrorResponse" }, "example": { "error": "CHANNEL_NOT_FOUND" } } } }, "TemplatesNotSupported": { "description": "Selected channel provider does not support Meta templates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateListErrorResponse" }, "example": { "error": "TEMPLATES_NOT_SUPPORTED" } } } }, "TemplatesNotConfigured": { "description": "Selected channel has no usable WABA configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateListErrorResponse" }, "example": { "error": "TEMPLATES_NOT_CONFIGURED" } } } }, "ProviderRequestFailed": { "description": "Meta request failed or returned a malformed successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateListErrorResponse" }, "example": { "error": "PROVIDER_REQUEST_FAILED" } } } } } } }