Twilio Configuration API

openapi: 3.2.0
info:
  title: Twilio Configuration API
  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
  termsOfService: https://www.twilio.com/legal/tos
  version: '1.0'
  description: 'Operations tagged Configuration across 2 of this provider''s published API definitions: conversations-openapi-original.yml, twilio-flex-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://conversations.twilio.com
- url: https://flex-api.twilio.com/v1
  description: Twilio Flex API v1
- url: https://flex-api.twilio.com/v2
  description: Twilio Flex API v2
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
      summary: Fetch configuration
      x-summary-source: derived
    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'
      summary: Update configuration
      x-summary-source: derived
  /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
      summary: List configuration address
      x-summary-source: derived
    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'
      summary: Create configuration address
      x-summary-source: derived
  /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
      summary: Fetch configuration address
      x-summary-source: derived
    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'
      summary: Update configuration address
      x-summary-source: derived
    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
      summary: Delete configuration address
      x-summary-source: derived
  /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
      summary: Fetch configuration webhook
      x-summary-source: derived
    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'
      summary: Update configuration webhook
      x-summary-source: derived
  /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
      security:
      - accountSid_authToken: []
    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
      security:
      - accountSid_authToken: []
    servers:
    - url: https://flex-api.twilio.com/v1
      description: Twilio Flex API v1
    - url: https://flex-api.twilio.com/v2
      description: Twilio Flex API v2
components:
  schemas:
    configuration_address_enum_auto_creation_type:
      type: string
      enum:
      - webhook
      - studio
      - default
    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_type:
      type: string
      enum:
      - sms
      - whatsapp
      - messenger
      - gbm
      - email
    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.
    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.
    conversations.v1.configuration.configuration_webhook:
      type: object
      properties:
        account_sid:
          type:
          - string
          - 'null'
          minLength: 34
          maxLength: 34
          pattern: ^AC[0-9a-fA-F]{32}$
          description: The unique ID of the [Account](https://www.twilio.com/docs/iam/api/account) responsible for this conversation.
        method:
          type:
          - string
          - 'null'
          $ref: '#/components/schemas/configuration_webhook_enum_method'
          description: The HTTP method to be used when sending a webhook request.
        filters:
          type:
          - array
          - 'null'
          items:
            type: string
          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
          - 'null'
          description: The absolute url the pre-event webhook request should be sent to.
        post_webhook_url:
          type:
          - string
          - 'null'
          description: The absolute url the post-event webhook request should be sent to.
        target:
          type:
          - string
          - 'null'
          $ref: '#/components/schemas/configuration_webhook_enum_target'
          description: The routing target of the webhook. Can be ordinary or route internally to Flex
        url:
          type:
          - string
          - 'null'
          format: uri
          description: An absolute API resource API resource URL for this webhook.
    conversations.v1.configuration:
      type: object
      properties:
        account_sid:
          type:
          - string
          - 'null'
          minLength: 34
          maxLength: 34
          pattern: ^AC[0-9a-fA-F]{32}$
          description: The SID of the [Account](https://www.twilio.com/docs/iam/api/account) responsible for this configuration.
        default_chat_service_sid:
          type:
          - string
          - 'null'
          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) used when creating a conversation.
        default_messaging_service_sid:
          type:
          - string
          - 'null'
          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) used when creating a conversation.
        default_inactive_timer:
          type:
          - string
          - 'null'
          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
          - 'null'
          description: Default ISO8601 duration when conversation will be switched to `closed` state. Minimum value for this timer is 10 minutes.
        url:
          type:
          - string
          - 'null'
          format: uri
          description: An absolute API resource URL for this global configuration.
        links:
          type:
          - object
          - 'null'
          format: uri-map
          description: Contains absolute API resource URLs to access the webhook and default service configurations.
    configuration_address_enum_method:
      type: string
      enum:
      - GET
      - POST
    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_address:
      type: object
      properties:
        sid:
          type:
          - string
          - 'null'
          minLength: 34
          maxLength: 34
          pattern: ^IG[0-9a-fA-F]{32}$
          description: A 34 character string that uniquely identifies this resource.
        account_sid:
          type:
          - string
          - 'null'
          minLength: 34
          maxLength: 34
          pattern: ^AC[0-9a-fA-F]{32}$
          description: The unique ID of the [Account](https://www.twilio.com/docs/iam/api/account) the address belongs to
        type:
          type:
          - string
          - 'null'
          description: Type of Address, value can be `whatsapp` or `sms`.
        address:
          type:
          - string
          - 'null'
          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
          - 'null'
          description: The human-readable name of this configuration, limited to 256 characters. Optional.
        auto_creation:
          description: Auto Creation configuration for the address.
        date_created:
          type:
          - string
          - 'null'
          format: date-time
          description: The date that this resource was created.
        date_updated:
          type:
          - string
          - 'null'
          format: date-time
          description: The date that this resource was last updated.
        url:
          type:
          - string
          - 'null'
          format: uri
          description: An absolute API resource URL for this address configuration.
        address_country:
          type:
          - string
          - 'null'
          description: An ISO 3166-1 alpha-2n country code which the address belongs to. This is currently only applicable to short code addresses.
    configuration_webhook_enum_target:
      type: string
      enum:
      - webhook
      - flex
    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
              - 'null'
              format: uri
            page:
              type: integer
            page_size:
              type: integer
            previous_page_url:
              type:
              - string
              - 'null'
              format: uri
            url:
              type: string
              format: uri
            key:
              type: string
    UpdateFlexConfigurationRequest:
      type: object
      properties:
        ui_attributes:
          type: object
        ui_language:
          type: string
        ui_version:
          type: string
        runtime_domain:
          type: string
    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
  securitySchemes:
    accountSid_authToken:
      type: http
      scheme: basic
externalDocs:
  description: Twilio Flex API Documentation
  url: https://www.twilio.com/docs/flex
x-refined-from:
- conversations-openapi-original.yml
- twilio-flex-openapi.yml
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.