{ "openapi": "3.0.1", "info": { "title": "Twilio - Messaging", "description": "This is the public Twilio REST API.", "termsOfService": "https://www.twilio.com/legal/tos", "contact": { "name": "Twilio Support", "url": "https://support.twilio.com", "email": "support@twilio.com" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" }, "version": "1.0.0", "x-twilio": { "apiStandards": "v0.1" } }, "security": [ { "accountSid_authToken": [] } ], "servers": [ { "url": "https://messaging.twilio.com" } ], "tags": [ { "name": "MessagingV3TypingIndicator", "description": "Send typing indicators to OTT channel recipients (WhatsApp, Apple Messages for Business, RCS).\n" }, { "name": "MessagingV3WhatsappBusinessAccount", "description": "Retrieve the WhatsApp Business Account associated with a Twilio account." }, { "name": "MessagingV3WhatsappMessageCostEstimate", "description": "Retrieve estimated cost and delivery ranges for WhatsApp marketing sends." } ], "paths": { "/v3/Indicators/Typing.json": { "servers": [ { "url": "https://messaging.twilio.com" } ], "description": "Send a typing indicator event for OTT channels (e.g., WhatsApp, Apple Messages for Business).", "x-twilio": { "defaultOutputProperties": [ "success" ], "mountName": "typing_indicator", "pathType": "list" }, "post": { "summary": "Send a typing indicator", "description": "Send a typing indicator to notify the recipient that you are composing a message. Supported channels: WhatsApp, Apple Messages for Business, RCS. The request body varies by channel \u2014 use the `channel` field as the discriminator.\n", "tags": [ "MessagingV3TypingIndicator" ], "operationId": "CreateV3TypingIndicator", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TypingIndicatorRequest" }, "examples": { "whatsapp_typing_indicator": { "summary": "WhatsApp Typing Indicator", "description": "Send a typing indicator for an active WhatsApp conversation", "value": { "channel": "WHATSAPP", "messageId": "SM1234567890abcdef1234567890abcdef" } }, "apple_typing_indicator": { "summary": "Apple Typing Indicator", "description": "Send a typing indicator for an Apple Messages for Business conversation", "value": { "channel": "APPLE", "from": "apple:a89a691c-15c0-4fd1-a589-1ded34b59c39", "to": "apple:urn:mbid:AQAAYyUbut6E4B3T9FLv5EbG", "event": "START" } }, "rcs_typing_indicator": { "summary": "RCS Typing Indicator", "description": "Send a typing indicator for an RCS conversation", "value": { "channel": "RCS", "from": "rcs:agent_id", "to": "rcs:+18001234567", "event": "START" } } } } } }, "responses": { "200": { "description": "Typing indicator was successfully sent to the recipient.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the typing indicator was sent successfully.", "example": true } } }, "examples": { "success": { "value": { "success": true } } } } }, "headers": { "Access-Control-Allow-Origin": { "description": "Specify the origin(s) allowed to access the resource", "schema": { "type": "string" }, "example": "*" }, "Access-Control-Allow-Methods": { "description": "Specify the HTTP methods allowed when accessing the resource", "schema": { "type": "string" }, "example": "POST, OPTIONS" }, "Access-Control-Allow-Headers": { "description": "Specify the headers allowed when accessing the resource", "schema": { "type": "string" }, "example": "Content-Type, Authorization" }, "Access-Control-Allow-Credentials": { "description": "Indicates whether the browser should include credentials", "schema": { "type": "boolean" } }, "Access-Control-Expose-Headers": { "description": "Headers exposed to the client", "schema": { "type": "string", "example": "X-Custom-Header1, X-Custom-Header2" } } } }, "400": { "description": "Invalid request. The request body is missing required fields or contains invalid values.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "Error message", "type": "string" }, "more_info": { "description": "Link to Error Code References", "type": "string" }, "status": { "description": "HTTP response status code", "type": "integer", "format": "int32" } } } } } }, "401": { "description": "Authentication credentials are missing or invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "Error message", "type": "string" }, "more_info": { "description": "Link to Error Code References", "type": "string" }, "status": { "description": "HTTP response status code", "type": "integer", "format": "int32" } } } } } }, "403": { "description": "The account is not authorized to send typing indicators for this channel.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "Error message", "type": "string" }, "more_info": { "description": "Link to Error Code References", "type": "string" }, "status": { "description": "HTTP response status code", "type": "integer", "format": "int32" } } } } } }, "404": { "description": "The requested resource was not found. The channel, sender, or recipient may not exist.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "Error message", "type": "string" }, "more_info": { "description": "Link to Error Code References", "type": "string" }, "status": { "description": "HTTP response status code", "type": "integer", "format": "int32" } } } } } }, "429": { "description": "Too many requests. The rate limit for typing indicators has been exceeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "Error message", "type": "string" }, "more_info": { "description": "Link to Error Code References", "type": "string" }, "status": { "description": "HTTP response status code", "type": "integer", "format": "int32" } } } } } } }, "security": [ { "accountSid_authToken": [] } ] } }, "/v3/MessageCostEstimate": { "servers": [ { "url": "https://messaging.twilio.com" } ], "description": "Returns the estimated cost and delivery range for a WhatsApp marketing send at a series of bid levels, for the WhatsApp Business Account resolved from the calling account.", "x-twilio": { "defaultOutputProperties": [ "currency", "estimates" ], "mountName": "message_cost_estimate", "pathType": "list" }, "get": { "summary": "Fetch a WhatsApp message cost estimate", "description": "Fetch the estimated cost and delivery ranges for WhatsApp Marketing Max Pricing messages sent to a single country, at multiple max price (bid) amounts. This applies to Marketing Max Pricing messages only. Estimates are generated from historical data over the requested lookback window and are informational only.", "tags": [ "MessagingV3WhatsappMessageCostEstimate" ], "operationId": "FetchV3WhatsappMessageCostEstimate", "parameters": [ { "name": "country", "in": "query", "required": true, "description": "The ISO-3166-1 alpha-2 country code to estimate for. Exactly one country is accepted.", "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "example": "IN" }, { "name": "lookbackWindow", "in": "query", "required": true, "description": "The historical lookback window used to compute the estimate.", "schema": { "type": "string", "enum": [ "L1D", "L7D", "L14D", "L28D" ] }, "example": "L7D" } ], "responses": { "200": { "description": "Message cost estimate was successfully computed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageCostEstimateResponse" }, "examples": { "fetch": { "value": { "currency": "USD", "country": "IN", "lookbackWindow": "L7D", "estimates": [ { "bidAmount": 400, "targetedUsers": 1000, "estimatedDeliveries": { "lower": 500, "upper": 570 }, "estimatedCost": { "lower": 389.74, "upper": 390.74 } } ], "disclaimer": "Estimates are historical and informational only; actual delivery and cost may vary." } } } } }, "headers": { "Access-Control-Allow-Origin": { "description": "Specify the origin(s) allowed to access the resource", "schema": { "type": "string" }, "example": "*" }, "Access-Control-Allow-Methods": { "description": "Specify the HTTP methods allowed when accessing the resource", "schema": { "type": "string" }, "example": "POST, OPTIONS" }, "Access-Control-Allow-Headers": { "description": "Specify the headers allowed when accessing the resource", "schema": { "type": "string" }, "example": "Content-Type, Authorization" }, "Access-Control-Allow-Credentials": { "description": "Indicates whether the browser should include credentials", "schema": { "type": "boolean" } }, "Access-Control-Expose-Headers": { "description": "Headers exposed to the client", "schema": { "type": "string", "example": "X-Custom-Header1, X-Custom-Header2" } } } }, "400": { "description": "Invalid request. The country or lookbackWindow is missing or malformed, more than one country was supplied, or the country is not eligible for cost estimation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "Error message", "type": "string" }, "more_info": { "description": "Link to Error Code References", "type": "string" }, "status": { "description": "HTTP response status code", "type": "integer", "format": "int32" } } } } } }, "401": { "description": "Authentication credentials are missing or invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "Error message", "type": "string" }, "more_info": { "description": "Link to Error Code References", "type": "string" }, "status": { "description": "HTTP response status code", "type": "integer", "format": "int32" } } } } } }, "404": { "description": "No WhatsApp Business Account is configured for the account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "Error message", "type": "string" }, "more_info": { "description": "Link to Error Code References", "type": "string" }, "status": { "description": "HTTP response status code", "type": "integer", "format": "int32" } } } } } }, "503": { "description": "The service is unavailable, the request timed out, or the WhatsApp API returned an error. The request should be retried.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Twilio-specific error code", "type": "integer", "format": "int32" }, "message": { "description": "Error message", "type": "string" }, "more_info": { "description": "Link to Error Code References", "type": "string" }, "status": { "description": "HTTP response status code", "type": "integer", "format": "int32" } } } } } } }, "security": [ { "accountSid_authToken": [] } ] } } }, "components": { "securitySchemes": { "accountSid_authToken": { "scheme": "basic", "type": "http" } }, "schemas": { "MessageCostEstimateResponse": { "type": "object", "description": "Estimated cost and delivery ranges at a series of bid levels.", "properties": { "currency": { "type": "string", "description": "The WhatsApp Business Account's currency (e.g. `USD`). `bidAmount` and cost bounds are in this currency's smallest unit.", "example": "USD" }, "country": { "type": "string", "description": "The ISO-3166-1 alpha-2 country code the estimate was computed for.", "example": "IN" }, "lookbackWindow": { "type": "string", "description": "The historical lookback window used to compute the estimate.", "enum": [ "L1D", "L7D", "L14D", "L28D" ] }, "estimates": { "type": "array", "description": "One entry per bid level.", "items": { "$ref": "#/components/schemas/MessageCostEstimateBidLevel" } }, "disclaimer": { "type": "string", "description": "Estimates are historical and informational only; actual delivery and cost may vary." } } }, "MessageCostEstimateBidLevel": { "type": "object", "description": "A single bid-level row in the message cost estimate.", "properties": { "bidAmount": { "type": "integer", "format": "int64", "description": "Max price per 1,000 message deliveries, in the smallest unit of `currency`.", "example": 400 }, "targetedUsers": { "type": "integer", "format": "int64", "description": "The normalized user base the estimate is scaled to (fixed at 1,000 during beta).", "example": 1000 }, "estimatedDeliveries": { "$ref": "#/components/schemas/MessageCostEstimateRange" }, "estimatedCost": { "$ref": "#/components/schemas/MessageCostEstimateRange" } } }, "MessageCostEstimateRange": { "type": "object", "description": "A lower/upper bound pair. For `estimatedCost`, the estimated average cost per 1,000 deliveries in the currency's smallest unit; for `estimatedDeliveries`, whole counts.", "properties": { "lower": { "type": "number" }, "upper": { "type": "number" } } }, "TypingIndicatorRequest": { "type": "object", "description": "Request body for sending a typing indicator. The schema varies by channel. Use the `channel` field to determine which properties are required.\n", "oneOf": [ { "$ref": "#/components/schemas/WhatsAppTypingIndicatorRequest" }, { "$ref": "#/components/schemas/AppleTypingIndicatorRequest" }, { "$ref": "#/components/schemas/RcsTypingIndicatorRequest" } ], "discriminator": { "propertyName": "channel", "mapping": { "WHATSAPP": "#/components/schemas/WhatsAppTypingIndicatorRequest", "APPLE": "#/components/schemas/AppleTypingIndicatorRequest", "RCS": "#/components/schemas/RcsTypingIndicatorRequest" } } }, "WhatsAppTypingIndicatorRequest": { "type": "object", "description": "Typing indicator request for WhatsApp channel. Requires a messageId from a recent inbound message.", "additionalProperties": false, "required": [ "channel", "messageId" ], "properties": { "channel": { "type": "string", "enum": [ "WHATSAPP" ], "description": "The messaging channel. Must be \"WHATSAPP\".", "example": "WHATSAPP" }, "messageId": { "type": "string", "pattern": "^(SM|MM)[0-9a-fA-F]{32}$", "description": "The SID of a recent inbound message from the recipient. Must be an SM or MM SID format.\n", "example": "SM1234567890abcdef1234567890abcdef" } } }, "AppleTypingIndicatorRequest": { "type": "object", "description": "Typing indicator request for Apple Messages for Business channel.", "additionalProperties": false, "required": [ "channel", "from", "to" ], "properties": { "channel": { "type": "string", "enum": [ "APPLE" ], "description": "The messaging channel. Must be \"APPLE\".", "example": "APPLE" }, "from": { "type": "string", "description": "The Apple Messages for Business identifier of the sender (business).", "example": "apple:a89a691c-15c0-4fd1-a589-1ded34b59c39" }, "to": { "type": "string", "description": "The Apple Messages for Business identifier of the recipient (customer).", "example": "apple:urn:mbid:AQAAYyUbut6E4B3T9FLv5EbG" }, "event": { "type": "string", "enum": [ "START", "END" ], "default": "START", "description": "The type of typing event. \"START\" indicates the agent began typing, \"END\" indicates the agent stopped typing. Defaults to \"START\".\n", "example": "START" } } }, "RcsTypingIndicatorRequest": { "type": "object", "description": "Typing indicator request for RCS channel.", "additionalProperties": false, "required": [ "channel", "from", "to" ], "properties": { "channel": { "type": "string", "enum": [ "RCS" ], "description": "The messaging channel. Must be \"RCS\".", "example": "RCS" }, "from": { "type": "string", "description": "The RCS agent identifier of the sender (business).", "example": "rcs:agent_id" }, "to": { "type": "string", "description": "The RCS recipient identifier in E.164 format prefixed with \"rcs:\".", "example": "rcs:+18001234567" }, "event": { "type": "string", "enum": [ "START" ], "default": "START", "description": "The type of typing event. Currently only \"START\" is supported for RCS, indicating the agent began typing. Defaults to \"START\".\n", "example": "START" } } } } } }