openapi: 3.0.1 info: title: Twilio - Accounts A2p Configuration API 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.52.0 servers: - url: https://accounts.twilio.com tags: - name: Configuration paths: /v1/Configuration: servers: - url: https://conversations.twilio.com description: The Configuration resource manages a set of account-level settings applicable to the Conversations API. x-twilio: defaultOutputProperties: - account_sid - default_chat_service_sid - default_messaging_service_sid pathType: instance get: description: Fetch the global configuration of conversations on your account tags: - Configuration responses: '200': content: application/json: schema: $ref: '#/components/schemas/conversations.v1.configuration' description: OK security: - accountSid_authToken: [] operationId: FetchConfiguration x-maturity: - GA post: description: Update the global configuration of conversations on your account tags: - Configuration responses: '200': content: application/json: schema: $ref: '#/components/schemas/conversations.v1.configuration' description: OK security: - accountSid_authToken: [] operationId: UpdateConfiguration x-maturity: - GA requestBody: content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/UpdateConfigurationRequest' /v1/Configuration/Addresses: servers: - url: https://conversations.twilio.com description: Address Configuration resource manages the configurations related to a unique address within Conversations x-twilio: defaultOutputProperties: - sid - type - address - friendly_name pathType: list mountName: address_configurations get: description: Retrieve a list of address configurations for an account tags: - Configuration parameters: - name: Type in: query description: 'Filter the address configurations by its type. This value can be one of: `whatsapp`, `sms`.' schema: type: string - name: PageSize in: query description: How many resources to return in each list page. The default is 50, and the maximum is 1000. schema: type: integer minimum: 1 maximum: 1000 - name: Page in: query description: The page index. This value is simply for client state. schema: type: integer minimum: 0 - name: PageToken in: query description: The page token. This is provided by the API. schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/ListConfigurationAddressResponse' description: OK security: - accountSid_authToken: [] operationId: ListConfigurationAddress x-maturity: - GA post: description: Create a new address configuration tags: - Configuration responses: '201': content: application/json: schema: $ref: '#/components/schemas/conversations.v1.configuration_address' description: Created security: - accountSid_authToken: [] operationId: CreateConfigurationAddress x-maturity: - GA requestBody: content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/CreateConfigurationAddressRequest' /v1/Configuration/Addresses/{Sid}: servers: - url: https://conversations.twilio.com description: Address Configuration resource manages the configurations related to a unique address within Conversations x-twilio: defaultOutputProperties: - sid - type - address - friendly_name pathType: instance mountName: address_configurations get: description: 'Fetch an address configuration ' tags: - Configuration parameters: - name: Sid in: path description: The SID of the Address Configuration resource. This value can be either the `sid` or the `address` of the configuration schema: type: string required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/conversations.v1.configuration_address' description: OK security: - accountSid_authToken: [] operationId: FetchConfigurationAddress x-maturity: - GA post: description: Update an existing address configuration tags: - Configuration parameters: - name: Sid in: path description: The SID of the Address Configuration resource. This value can be either the `sid` or the `address` of the configuration schema: type: string required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/conversations.v1.configuration_address' description: OK security: - accountSid_authToken: [] operationId: UpdateConfigurationAddress x-maturity: - GA requestBody: content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/UpdateConfigurationAddressRequest' delete: description: Remove an existing address configuration tags: - Configuration parameters: - name: Sid in: path description: The SID of the Address Configuration resource. This value can be either the `sid` or the `address` of the configuration schema: type: string required: true responses: '204': description: The resource was deleted successfully. security: - accountSid_authToken: [] operationId: DeleteConfigurationAddress x-maturity: - GA /v1/Configuration/Webhooks: servers: - url: https://conversations.twilio.com description: A Webhook resource manages a service-level set of callback URLs and their configuration for receiving all conversation events. x-twilio: defaultOutputProperties: - target - method - pre_webhook_url - post_webhook_url pathType: instance parent: /Configuration get: description: '' tags: - Configuration responses: '200': content: application/json: schema: $ref: '#/components/schemas/conversations.v1.configuration.configuration_webhook' description: OK security: - accountSid_authToken: [] operationId: FetchConfigurationWebhook x-maturity: - GA post: description: '' tags: - Configuration responses: '200': content: application/json: schema: $ref: '#/components/schemas/conversations.v1.configuration.configuration_webhook' description: OK security: - accountSid_authToken: [] operationId: UpdateConfigurationWebhook x-maturity: - GA requestBody: content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/UpdateConfigurationWebhookRequest' /Configuration: get: operationId: fetchConfiguration summary: Twilio Fetch Flex Configuration description: Retrieve the current Flex configuration including UI attributes, enabled channels, and runtime settings. tags: - Configuration parameters: - name: UiVersion in: query description: The Flex UI version to fetch configuration for schema: type: string responses: '200': description: Flex configuration content: application/json: schema: $ref: '#/components/schemas/FlexConfiguration' '401': description: Unauthorized post: operationId: updateConfiguration summary: Twilio Update Flex Configuration description: Update the Flex configuration settings. tags: - Configuration requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateFlexConfigurationRequest' responses: '200': description: Configuration updated content: application/json: schema: $ref: '#/components/schemas/FlexConfiguration' '400': description: Invalid request components: schemas: configuration_webhook_enum_target: type: string enum: - webhook - flex CreateConfigurationAddressRequest: type: object required: - Type - Address properties: Type: type: string $ref: '#/components/schemas/configuration_address_enum_type' description: Type of Address. Value can be `whatsapp` or `sms`. Address: type: string description: The unique address to be configured. The address can be a whatsapp address or phone number FriendlyName: type: string description: The human-readable name of this configuration, limited to 256 characters. Optional. AutoCreation.Enabled: type: boolean description: Enable/Disable auto-creating conversations for messages to this address AutoCreation.Type: type: string $ref: '#/components/schemas/configuration_address_enum_auto_creation_type' description: Type of Auto Creation. Value can be one of `webhook`, `studio` or `default`. `default` creates a new Conversation under the default Conversation service, without a webhook or Studio integration. AutoCreation.ConversationServiceSid: type: string minLength: 34 maxLength: 34 pattern: ^IS[0-9a-fA-F]{32}$ description: Conversation Service for the auto-created conversation. If not set, the conversation is created in the default service. AutoCreation.WebhookUrl: type: string description: For type `webhook`, the url for the webhook request. AutoCreation.WebhookMethod: type: string $ref: '#/components/schemas/configuration_address_enum_method' description: For type `webhook`, the HTTP method to be used when sending a webhook request. AutoCreation.WebhookFilters: type: array items: type: string description: 'The list of events, firing webhook event for this Conversation. Values can be any of the following: `onMessageAdded`, `onMessageUpdated`, `onMessageRemoved`, `onConversationUpdated`, `onConversationStateUpdated`, `onConversationRemoved`, `onParticipantAdded`, `onParticipantUpdated`, `onParticipantRemoved`, `onDeliveryUpdated`' AutoCreation.StudioFlowSid: type: string minLength: 34 maxLength: 34 pattern: ^FW[0-9a-fA-F]{32}$ description: For type `studio`, the studio flow SID where the webhook should be sent to. AutoCreation.StudioRetryCount: type: integer description: For type `studio`, number of times to retry the webhook request AddressCountry: type: string description: An ISO 3166-1 alpha-2n country code which the address belongs to. This is currently only applicable to short code addresses. conversations.v1.configuration.configuration_webhook: type: object properties: account_sid: type: string minLength: 34 maxLength: 34 pattern: ^AC[0-9a-fA-F]{32}$ nullable: true description: The unique ID of the [Account](https://www.twilio.com/docs/iam/api/account) responsible for this conversation. method: type: string $ref: '#/components/schemas/configuration_webhook_enum_method' nullable: true description: The HTTP method to be used when sending a webhook request. filters: type: array items: type: string nullable: true description: 'The list of webhook event triggers that are enabled for this Service: `onMessageAdded`, `onMessageUpdated`, `onMessageRemoved`, `onConversationUpdated`, `onConversationRemoved`, `onParticipantAdded`, `onParticipantUpdated`, `onParticipantRemoved`' pre_webhook_url: type: string nullable: true description: The absolute url the pre-event webhook request should be sent to. post_webhook_url: type: string nullable: true description: The absolute url the post-event webhook request should be sent to. target: type: string $ref: '#/components/schemas/configuration_webhook_enum_target' nullable: true description: The routing target of the webhook. Can be ordinary or route internally to Flex url: type: string format: uri nullable: true description: An absolute API resource API resource URL for this webhook. UpdateConfigurationRequest: type: object properties: DefaultChatServiceSid: type: string minLength: 34 maxLength: 34 pattern: ^IS[0-9a-fA-F]{32}$ description: The SID of the default [Conversation Service](https://www.twilio.com/docs/conversations/api/service-resource) to use when creating a conversation. DefaultMessagingServiceSid: type: string minLength: 34 maxLength: 34 pattern: ^MG[0-9a-fA-F]{32}$ description: The SID of the default [Messaging Service](https://www.twilio.com/docs/messaging/api/service-resource) to use when creating a conversation. DefaultInactiveTimer: type: string description: Default ISO8601 duration when conversation will be switched to `inactive` state. Minimum value for this timer is 1 minute. DefaultClosedTimer: type: string description: Default ISO8601 duration when conversation will be switched to `closed` state. Minimum value for this timer is 10 minutes. conversations.v1.configuration_address: type: object properties: sid: type: string minLength: 34 maxLength: 34 pattern: ^IG[0-9a-fA-F]{32}$ nullable: true description: A 34 character string that uniquely identifies this resource. account_sid: type: string minLength: 34 maxLength: 34 pattern: ^AC[0-9a-fA-F]{32}$ nullable: true description: The unique ID of the [Account](https://www.twilio.com/docs/iam/api/account) the address belongs to type: type: string nullable: true description: Type of Address, value can be `whatsapp` or `sms`. address: type: string nullable: true description: The unique address to be configured. The address can be a whatsapp address or phone number x-twilio: pii: handling: standard deleteSla: 30 friendly_name: type: string nullable: true description: The human-readable name of this configuration, limited to 256 characters. Optional. auto_creation: nullable: true description: Auto Creation configuration for the address. date_created: type: string format: date-time nullable: true description: The date that this resource was created. date_updated: type: string format: date-time nullable: true description: The date that this resource was last updated. url: type: string format: uri nullable: true description: An absolute API resource URL for this address configuration. address_country: type: string nullable: true description: An ISO 3166-1 alpha-2n country code which the address belongs to. This is currently only applicable to short code addresses. FlexConfiguration: type: object properties: account_sid: type: string pattern: ^AC[0-9a-fA-F]{32}$ status: type: string enum: - ok - inDeployment - notDeployed task_router_workspace_sid: type: string chat_service_instance_sid: type: string flex_service_instance_sid: type: string ui_language: type: string ui_attributes: type: object description: Custom UI configuration attributes ui_dependencies: type: object ui_version: type: string flex_url: type: string format: uri flex_insights_hr: type: object flex_insights_drilldown: type: boolean channel_configs: type: array items: type: object runtime_domain: type: string messaging_service_instance_sid: type: string serverless_service_sids: type: array items: type: string date_created: type: string format: date-time date_updated: type: string format: date-time url: type: string format: uri UpdateConfigurationWebhookRequest: type: object properties: Method: type: string description: The HTTP method to be used when sending a webhook request. Filters: type: array items: type: string description: 'The list of webhook event triggers that are enabled for this Service: `onMessageAdded`, `onMessageUpdated`, `onMessageRemoved`, `onConversationUpdated`, `onConversationRemoved`, `onParticipantAdded`, `onParticipantUpdated`, `onParticipantRemoved`' PreWebhookUrl: type: string description: The absolute url the pre-event webhook request should be sent to. PostWebhookUrl: type: string description: The absolute url the post-event webhook request should be sent to. Target: type: string $ref: '#/components/schemas/configuration_webhook_enum_target' description: The routing target of the webhook. configuration_address_enum_type: type: string enum: - sms - whatsapp - messenger - gbm - email conversations.v1.configuration: type: object properties: account_sid: type: string minLength: 34 maxLength: 34 pattern: ^AC[0-9a-fA-F]{32}$ nullable: true description: The SID of the [Account](https://www.twilio.com/docs/iam/api/account) responsible for this configuration. default_chat_service_sid: type: string minLength: 34 maxLength: 34 pattern: ^IS[0-9a-fA-F]{32}$ nullable: true description: The SID of the default [Conversation Service](https://www.twilio.com/docs/conversations/api/service-resource) used when creating a conversation. default_messaging_service_sid: type: string minLength: 34 maxLength: 34 pattern: ^MG[0-9a-fA-F]{32}$ nullable: true description: The SID of the default [Messaging Service](https://www.twilio.com/docs/messaging/api/service-resource) used when creating a conversation. default_inactive_timer: type: string nullable: true description: Default ISO8601 duration when conversation will be switched to `inactive` state. Minimum value for this timer is 1 minute. default_closed_timer: type: string nullable: true description: Default ISO8601 duration when conversation will be switched to `closed` state. Minimum value for this timer is 10 minutes. url: type: string format: uri nullable: true description: An absolute API resource URL for this global configuration. links: type: object format: uri-map nullable: true description: Contains absolute API resource URLs to access the webhook and default service configurations. configuration_webhook_enum_method: type: string enum: - GET - POST UpdateConfigurationAddressRequest: type: object properties: FriendlyName: type: string description: The human-readable name of this configuration, limited to 256 characters. Optional. AutoCreation.Enabled: type: boolean description: Enable/Disable auto-creating conversations for messages to this address AutoCreation.Type: type: string $ref: '#/components/schemas/configuration_address_enum_auto_creation_type' description: Type of Auto Creation. Value can be one of `webhook`, `studio` or `default`. AutoCreation.ConversationServiceSid: type: string minLength: 34 maxLength: 34 pattern: ^IS[0-9a-fA-F]{32}$ description: Conversation Service for the auto-created conversation. If not set, the conversation is created in the default service. AutoCreation.WebhookUrl: type: string description: For type `webhook`, the url for the webhook request. AutoCreation.WebhookMethod: type: string $ref: '#/components/schemas/configuration_address_enum_method' description: For type `webhook`, the HTTP method to be used when sending a webhook request. AutoCreation.WebhookFilters: type: array items: type: string description: 'The list of events, firing webhook event for this Conversation. Values can be any of the following: `onMessageAdded`, `onMessageUpdated`, `onMessageRemoved`, `onConversationUpdated`, `onConversationStateUpdated`, `onConversationRemoved`, `onParticipantAdded`, `onParticipantUpdated`, `onParticipantRemoved`, `onDeliveryUpdated`' AutoCreation.StudioFlowSid: type: string minLength: 34 maxLength: 34 pattern: ^FW[0-9a-fA-F]{32}$ description: For type `studio`, the studio flow SID where the webhook should be sent to. AutoCreation.StudioRetryCount: type: integer description: For type `studio`, number of times to retry the webhook request configuration_address_enum_method: type: string enum: - GET - POST UpdateFlexConfigurationRequest: type: object properties: ui_attributes: type: object ui_language: type: string ui_version: type: string runtime_domain: type: string ListConfigurationAddressResponse: type: object properties: address_configurations: type: array items: $ref: '#/components/schemas/conversations.v1.configuration_address' meta: type: object properties: first_page_url: type: string format: uri next_page_url: type: string format: uri nullable: true page: type: integer page_size: type: integer previous_page_url: type: string format: uri nullable: true url: type: string format: uri key: type: string configuration_address_enum_auto_creation_type: type: string enum: - webhook - studio - default securitySchemes: accountSid_authToken: type: http scheme: basic x-maturity: - name: GA description: This product is Generally Available. - name: Beta description: PLEASE NOTE that this is a Beta product that is subject to change. Use it with caution.