openapi: 3.2.0
info:
  version: 2.0.0
  x-latency-category: responsive
  x-endpoint-cost: light
  title: Telnyx RCS Agents API
  description: SIP trunking, SMS, MMS, Call Control and Telephony Data Services.
  contact:
    email: support@telnyx.com
servers:
- url: https://api.telnyx.com/v2
  description: Version 2.0.0 of the Telnyx API
security:
- bearerAuth: []
tags:
- name: RCS Agents
  description: Manage RCS agent registration, testing, verification, and launch.
paths:
  /rcs/agents:
    get:
      tags:
      - RCS Agents
      summary: List RCS agents
      description: Lists RCS agents owned by the authenticated organization, optionally filtered by brand.
      operationId: ListRcsAgents
      parameters:
      - name: brand_id
        in: query
        required: false
        description: Only return agents belonging to this brand.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: RCS agents owned by the organization.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AgentResponse'
        '401':
          $ref: '#/components/responses/rcs-registration_Unauthorized'
        '404':
          $ref: '#/components/responses/rcs-registration_NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
    post:
      tags:
      - RCS Agents
      summary: Create an RCS agent
      description: Creates an editable RCS agent draft under a brand. The `Idempotency-Key` is scoped to the authenticated organization. Reusing the key with the same request returns the original agent, while reusing it with a different request returns a conflict.
      operationId: CreateRcsAgent
      parameters:
      - $ref: '#/components/parameters/rcs-registration_IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentCreateRequest'
      responses:
        '201':
          description: The agent draft was created or replayed from the idempotency record.
          headers:
            Idempotent-Replayed:
              description: Present with value `true` when a successful response was replayed for the supplied idempotency key.
              schema:
                type: boolean
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
        '400':
          $ref: '#/components/responses/rcs-registration_BadRequest'
        '401':
          $ref: '#/components/responses/rcs-registration_Unauthorized'
        '404':
          $ref: '#/components/responses/rcs-registration_NotFound'
        '409':
          $ref: '#/components/responses/rcs-registration_Conflict'
        '422':
          $ref: '#/components/responses/ValidationError'
        '503':
          $ref: '#/components/responses/DependencyUnavailable'
  /rcs/agents/{id}:
    get:
      tags:
      - RCS Agents
      summary: Retrieve an RCS agent
      description: Retrieves an RCS agent, section statuses, test devices, carrier approvals, and provider capabilities.
      operationId: RetrieveRcsAgent
      parameters:
      - $ref: '#/components/parameters/AgentId'
      responses:
        '200':
          description: The requested RCS agent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
        '401':
          $ref: '#/components/responses/rcs-registration_Unauthorized'
        '404':
          $ref: '#/components/responses/rcs-registration_NotFound'
    patch:
      tags:
      - RCS Agents
      summary: Update an RCS agent
      description: Updates one or more fields on an agent while its status is `CREATED`. Submitted agents cannot be changed through this endpoint.
      operationId: UpdateRcsAgent
      parameters:
      - $ref: '#/components/parameters/AgentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentUpdateRequest'
      responses:
        '200':
          description: The updated RCS agent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
        '401':
          $ref: '#/components/responses/rcs-registration_Unauthorized'
        '404':
          $ref: '#/components/responses/rcs-registration_NotFound'
        '409':
          $ref: '#/components/responses/rcs-registration_Conflict'
        '422':
          $ref: '#/components/responses/ValidationError'
        '503':
          $ref: '#/components/responses/DependencyUnavailable'
  /rcs/agents/{id}/carrier_approvals:
    get:
      tags:
      - RCS Agents
      summary: List RCS agent carrier approvals
      description: Lists carrier approval records for an RCS agent. The provider may expose per-carrier, hub-level, or bot-level approval status.
      operationId: ListRcsAgentCarrierApprovals
      parameters:
      - $ref: '#/components/parameters/AgentId'
      responses:
        '200':
          description: Carrier approval records for the agent.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CarrierApprovalResponse'
        '401':
          $ref: '#/components/responses/rcs-registration_Unauthorized'
        '404':
          $ref: '#/components/responses/rcs-registration_NotFound'
  /rcs/agents/{id}/launch:
    post:
      tags:
      - RCS Agents
      summary: Submit an RCS agent for launch
      description: Adds the campaign and testing configuration, then starts asynchronous carrier launch. Agent basics must already be submitted. Repeating a launch that is already in progress returns the current agent without creating new work.
      operationId: LaunchRcsAgent
      parameters:
      - $ref: '#/components/parameters/AgentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentLaunchRequest'
      responses:
        '202':
          description: The launch submission was accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
        '401':
          $ref: '#/components/responses/rcs-registration_Unauthorized'
        '404':
          $ref: '#/components/responses/rcs-registration_NotFound'
        '409':
          $ref: '#/components/responses/rcs-registration_Conflict'
        '422':
          $ref: '#/components/responses/ValidationError'
  /rcs/agents/{id}/submit:
    post:
      tags:
      - RCS Agents
      summary: Submit RCS agent basics
      description: Starts asynchronous provider provisioning and submits the agent's basic configuration. The brand must be `VERIFIED`. Repeating this request for an in-progress agent returns its current state without creating new work.
      operationId: SubmitRcsAgent
      parameters:
      - $ref: '#/components/parameters/AgentId'
      responses:
        '202':
          description: The basic agent submission was accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
        '401':
          $ref: '#/components/responses/rcs-registration_Unauthorized'
        '404':
          $ref: '#/components/responses/rcs-registration_NotFound'
        '409':
          $ref: '#/components/responses/rcs-registration_Conflict'
  /rcs/agents/{id}/test_devices:
    get:
      tags:
      - RCS Agents
      summary: List RCS agent test devices
      description: Lists test devices attached to an RCS agent.
      operationId: ListRcsAgentTestDevices
      parameters:
      - $ref: '#/components/parameters/AgentId'
      responses:
        '200':
          description: Test devices attached to the agent.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TestDeviceResponse'
        '401':
          $ref: '#/components/responses/rcs-registration_Unauthorized'
        '404':
          $ref: '#/components/responses/rcs-registration_NotFound'
    post:
      tags:
      - RCS Agents
      summary: Add an RCS agent test device
      description: Adds an RCS-capable test number after provider agent creation. Repeating the request for a number already attached to the agent returns the existing test device.
      operationId: AddRcsAgentTestDevice
      parameters:
      - $ref: '#/components/parameters/AgentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TestDeviceCreateRequest'
      responses:
        '201':
          description: The test device was added or already existed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestDeviceResponse'
        '401':
          $ref: '#/components/responses/rcs-registration_Unauthorized'
        '404':
          $ref: '#/components/responses/rcs-registration_NotFound'
        '409':
          $ref: '#/components/responses/rcs-registration_Conflict'
        '422':
          $ref: '#/components/responses/ValidationError'
        '502':
          $ref: '#/components/responses/ProviderError'
  /rcs/agents/{id}/test_devices/{test_device_id}:
    delete:
      tags:
      - RCS Agents
      summary: Remove an RCS agent test device
      description: Removes a test device from an RCS agent and its provider registration.
      operationId: RemoveRcsAgentTestDevice
      parameters:
      - $ref: '#/components/parameters/AgentId'
      - $ref: '#/components/parameters/TestDeviceId'
      responses:
        '204':
          description: The test device was removed.
        '401':
          $ref: '#/components/responses/rcs-registration_Unauthorized'
        '404':
          $ref: '#/components/responses/rcs-registration_NotFound'
        '502':
          $ref: '#/components/responses/ProviderError'
components:
  schemas:
    HttpUrl:
      type: string
      format: uri
      minLength: 1
      pattern: ^[Hh][Tt][Tt][Pp][Ss]?://
    CarrierApprovalScope:
      type: string
      enum:
      - carrier
      - hub
      - bot
    rcs-registration_ErrorResponse:
      type: object
      properties:
        detail:
          type: string
        errors:
          type: array
          items:
            type: object
            additionalProperties: true
      additionalProperties: true
      example:
        detail: The requested RCS resource was not found.
    BillingCategory:
      type: string
      enum:
      - NON_CONVERSATIONAL
      - CONVERSATIONAL
    AgentCampaignConfiguration:
      type: object
      additionalProperties: false
      properties:
        company_overview:
          type: string
          minLength: 1
          maxLength: 2000
        agent_overview:
          type:
          - string
          - 'null'
          minLength: 1
          maxLength: 2000
        interactions:
          type: array
          items:
            $ref: '#/components/schemas/AgentInteraction'
        message_examples:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 2000
        consent_settings:
          oneOf:
          - $ref: '#/components/schemas/AgentConsentConfiguration'
          - type: 'null'
        additional_information:
          type:
          - string
          - 'null'
          minLength: 1
          maxLength: 2000
      required:
      - company_overview
    AgentOptInMethod:
      type: object
      propertyNames:
        enum:
        - method_type
        - description
      properties:
        method_type:
          $ref: '#/components/schemas/AgentOptInMethodType'
        description:
          type:
          - string
          - 'null'
          minLength: 1
          maxLength: 2000
          description: Required when method_type is `OTHER`.
      required:
      - method_type
      allOf:
      - if:
          properties:
            method_type:
              const: OTHER
          required:
          - method_type
        then:
          properties:
            description:
              type: string
              minLength: 1
              maxLength: 2000
          required:
          - description
    AgentCreateRequest:
      type: object
      additionalProperties: false
      properties:
        brand_id:
          type: string
          format: uuid
        display_name:
          type: string
          minLength: 1
          maxLength: 40
        use_case:
          $ref: '#/components/schemas/AgentUseCase'
        profile_id:
          type:
          - string
          - 'null'
          maxLength: 36
          description: A Messaging Profile owned by the authenticated organization. When omitted, the agent inherits the brand profile.
        hosting_region:
          type:
          - string
          - 'null'
          maxLength: 32
        configuration:
          $ref: '#/components/schemas/AgentConfiguration'
      required:
      - brand_id
      - display_name
      - use_case
      - configuration
      example:
        brand_id: 11111111-1111-4111-8111-111111111111
        display_name: Acme Order Updates
        use_case: TRANSACTIONAL
        configuration:
          basics:
            description: Order confirmations and delivery updates
            logo_url: https://www.example.com/rcs/logo.png
            hero_url: https://www.example.com/rcs/hero.png
            brand_color: '#123456'
            privacy_policy_url: https://www.example.com/privacy
            terms_and_conditions_url: https://www.example.com/terms
            email:
              address: support@example.com
              label: Support
    CarrierApprovalResponse:
      type: object
      additionalProperties: false
      properties:
        approval_id:
          type: string
          format: uuid
        scope_type:
          $ref: '#/components/schemas/CarrierApprovalScope'
        status:
          $ref: '#/components/schemas/CarrierApprovalStatus'
        carrier:
          type:
          - string
          - 'null'
        submitted_at:
          type:
          - string
          - 'null'
          format: date-time
        approved_at:
          type:
          - string
          - 'null'
          format: date-time
        rejected_reason:
          type:
          - string
          - 'null'
      required:
      - approval_id
      - scope_type
      - status
      - carrier
      - submitted_at
      - approved_at
      - rejected_reason
      example:
        approval_id: 33333333-3333-4333-8333-333333333333
        scope_type: hub
        status: SUBMITTED
        carrier: null
        submitted_at: '2026-08-10T12:00:00Z'
        approved_at: null
        rejected_reason: null
    AgentSubmissionStatus:
      type: string
      enum:
      - SUBMITTED
      - APPROVED
      - REJECTED
    AgentResponse:
      type: object
      additionalProperties: false
      properties:
        agent_id:
          type: string
          format: uuid
        brand_id:
          type: string
          format: uuid
        display_name:
          type: string
        use_case:
          $ref: '#/components/schemas/AgentUseCase'
        status:
          $ref: '#/components/schemas/AgentState'
        profile_id:
          type:
          - string
          - 'null'
        basics_status:
          oneOf:
          - $ref: '#/components/schemas/AgentSubmissionStatus'
          - type: 'null'
        campaign_status:
          oneOf:
          - $ref: '#/components/schemas/AgentSubmissionStatus'
          - type: 'null'
        testing_status:
          oneOf:
          - $ref: '#/components/schemas/AgentSubmissionStatus'
          - type: 'null'
        billing_category:
          oneOf:
          - $ref: '#/components/schemas/BillingCategory'
          - type: 'null'
        hosting_region:
          type:
          - string
          - 'null'
        configuration:
          $ref: '#/components/schemas/AgentConfiguration'
        carrier_approvals:
          type: array
          items:
            $ref: '#/components/schemas/CarrierApprovalResponse'
        test_devices:
          type: array
          items:
            $ref: '#/components/schemas/TestDeviceResponse'
        capabilities:
          $ref: '#/components/schemas/CapabilitiesResponse'
      required:
      - agent_id
      - brand_id
      - display_name
      - use_case
      - status
      - profile_id
      - basics_status
      - campaign_status
      - testing_status
      - billing_category
      - hosting_region
      - configuration
      - carrier_approvals
      - test_devices
      - capabilities
      example:
        agent_id: 22222222-2222-4222-8222-222222222222
        brand_id: 11111111-1111-4111-8111-111111111111
        display_name: Acme Order Updates
        use_case: TRANSACTIONAL
        status: SUBMITTED
        profile_id: 40000000-0000-0000-0000-000000000001
        basics_status: SUBMITTED
        campaign_status: null
        testing_status: null
        billing_category: NON_CONVERSATIONAL
        hosting_region: null
        configuration:
          basics:
            description: Order confirmations and delivery updates
            logo_url: https://www.example.com/rcs/logo.png
            hero_url: https://www.example.com/rcs/hero.png
            brand_color: '#123456'
            privacy_policy_url: https://www.example.com/privacy
            terms_and_conditions_url: https://www.example.com/terms
            email:
              address: support@example.com
              label: Support
          campaign: null
          testing: null
        carrier_approvals: []
        test_devices: []
        capabilities:
          brand_entity: true
          brand_verification: true
          submission_sections: true
          distinct_launch_phase: false
          per_carrier_approval: false
          templates: false
          campaigns: false
          vendor_webhooks: false
          invite_test_devices: false
    CapabilitiesResponse:
      type: object
      additionalProperties: false
      properties:
        brand_entity:
          type: boolean
        brand_verification:
          type: boolean
        submission_sections:
          type: boolean
        distinct_launch_phase:
          type: boolean
        per_carrier_approval:
          type: boolean
        templates:
          type: boolean
        campaigns:
          type: boolean
        vendor_webhooks:
          type: boolean
        invite_test_devices:
          type: boolean
      required:
      - brand_entity
      - brand_verification
      - submission_sections
      - distinct_launch_phase
      - per_carrier_approval
      - templates
      - campaigns
      - vendor_webhooks
      - invite_test_devices
    AgentOptInMethodType:
      type: string
      enum:
      - SMS
      - WEBSITE
      - MOBILE_APP
      - QR_CODE
      - SALE_POINT
      - OTHER
    AgentUpdateRequest:
      type: object
      additionalProperties: false
      minProperties: 1
      properties:
        display_name:
          type: string
          minLength: 1
          maxLength: 40
        use_case:
          $ref: '#/components/schemas/AgentUseCase'
        profile_id:
          type: string
          maxLength: 36
        hosting_region:
          type: string
          maxLength: 32
        configuration:
          $ref: '#/components/schemas/AgentConfiguration'
      example:
        display_name: Acme Delivery Updates
    TestDeviceInviteStatus:
      type: string
      enum:
      - PENDING
      - ACCEPTED
      - DECLINED
    AgentLaunchRequest:
      type: object
      additionalProperties: false
      properties:
        campaign:
          $ref: '#/components/schemas/AgentLaunchCampaignConfiguration'
        testing:
          $ref: '#/components/schemas/AgentTestingConfiguration'
      required:
      - campaign
      - testing
      example:
        campaign:
          company_overview: Acme provides online retail services.
          agent_overview: The agent sends order confirmations and delivery updates.
          interactions:
          - interaction_type: TRANSACTIONAL_UPDATES
          message_examples:
          - Your Acme order is confirmed.
          - Your Acme order has shipped.
          - Your Acme order was delivered.
          consent_settings:
            opt_in_methods:
            - method_type: WEBSITE
            call_to_action: Select RCS updates during checkout.
            call_to_action_url: https://www.example.com/checkout
            call_to_action_media_url: https://www.example.com/rcs/opt-in.png
            double_opt_in: false
            opt_in_message: You are subscribed to Acme order updates.
            help_response: Contact support@example.com for help.
            opt_out_response: You will receive no more messages.
        testing:
          test_url: https://www.example.com/rcs/test-video
          additional_information: Demonstrates START, STOP, HELP, and an order-status interaction.
    CarrierApprovalStatus:
      type: string
      enum:
      - PENDING
      - SUBMITTED
      - APPROVED
      - REJECTED
    AgentTestingConfiguration:
      type: object
      additionalProperties: false
      properties:
        test_url:
          $ref: '#/components/schemas/HttpUrl'
          description: A publicly accessible test video or evidence URL.
        message_id:
          type:
          - string
          - 'null'
          minLength: 1
          maxLength: 255
        additional_information:
          type:
          - string
          - 'null'
          minLength: 1
          maxLength: 2000
      required:
      - test_url
    AgentBasicsConfiguration:
      type: object
      additionalProperties: false
      description: Basic agent identity and contact information. At least one complete phone, website, or email contact is required.
      properties:
        description:
          type: string
          minLength: 1
          maxLength: 100
        logo_url:
          $ref: '#/components/schemas/HttpUrl'
        hero_url:
          $ref: '#/components/schemas/HttpUrl'
        brand_color:
          type: string
          pattern: ^#(?:[0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$
        privacy_policy_url:
          $ref: '#/components/schemas/HttpUrl'
        terms_and_conditions_url:
          $ref: '#/components/schemas/HttpUrl'
        phone_number:
          oneOf:
          - $ref: '#/components/schemas/AgentPhoneContact'
          - type: 'null'
        website:
          oneOf:
          - $ref: '#/components/schemas/AgentWebsiteContact'
          - type: 'null'
        email:
          oneOf:
          - $ref: '#/components/schemas/AgentEmailContact'
          - type: 'null'
      anyOf:
      - required:
        - phone_number
        properties:
          phone_number:
            $ref: '#/components/schemas/AgentPhoneContact'
      - required:
        - website
        properties:
          website:
            $ref: '#/components/schemas/AgentWebsiteContact'
      - required:
        - email
        properties:
          email:
            $ref: '#/components/schemas/AgentEmailContact'
      required:
      - description
      - logo_url
      - hero_url
      - brand_color
      - privacy_policy_url
      - terms_and_conditions_url
    AgentInteractionType:
      type: string
      enum:
      - TRANSACTIONAL_UPDATES
      - CUSTOMER_SUPPORT
      - LOYALTY_OR_REWARD
      - MARKETING_OR_PROMOTIONAL
      - ACCOUNT_ALERTS
      - TWO_WAY_CONVERSATION
      - OTHER
    AgentUseCase:
      type: string
      enum:
      - MULTI_USE
      - PROMOTIONAL
      - TRANSACTIONAL
      - OTP
    AgentState:
      type: string
      enum:
      - CREATED
      - SUBMITTED
      - VERIFYING
      - VERIFIED
      - LAUNCHING
      - LAUNCHED
      - LIVE
      - REJECTED
      - FAILED
    AgentConsentConfiguration:
      type: object
      propertyNames:
        enum:
        - opt_in_methods
        - call_to_action
        - call_to_action_url
        - call_to_action_media_url
        - double_opt_in
        - double_opt_in_message
        - opt_in_message
        - help_response
        - opt_out_response
      properties:
        opt_in_methods:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/AgentOptInMethod'
        call_to_action:
          type: string
          minLength: 1
          maxLength: 2000
        call_to_action_url:
          oneOf:
          - $ref: '#/components/schemas/HttpUrl'
          - type: 'null'
          description: Required when an opt-in method is `WEBSITE`.
        call_to_action_media_url:
          oneOf:
          - $ref: '#/components/schemas/HttpUrl'
          - type: 'null'
          description: Required when an opt-in method is `WEBSITE` or `MOBILE_APP`.
        double_opt_in:
          type: boolean
        double_opt_in_message:
          type:
          - string
          - 'null'
          minLength: 1
          maxLength: 2000
          description: Required when double_opt_in is true.
        opt_in_message:
          type: string
          minLength: 1
          maxLength: 2000
        help_response:
          type: string
          minLength: 1
          maxLength: 2000
        opt_out_response:
          type: string
          minLength: 1
          maxLength: 2000
      required:
      - opt_in_methods
      - call_to_action
      - double_opt_in
      - opt_in_message
      - help_response
      - opt_out_response
      not:
        anyOf:
        - properties:
            opt_in_methods:
              contains:
                properties:
                  method_type:
                    const: WEBSITE
                required:
                - method_type
          required:
          - opt_in_methods
          anyOf:
          - not:
              properties:
                call_to_action_url: {}
              required:
              - call_to_action_url
          - properties:
              call_to_action_url:
                type: 'null'
          - not:
              properties:
                call_to_action_media_url: {}
              required:
              - call_to_action_media_url
          - properties:
              call_to_action_media_url:
                type: 'null'
        - properties:
            opt_in_methods:
              contains:
                properties:
                  method_type:
                    const: MOBILE_APP
                required:
                - method_type
          required:
          - opt_in_methods
          anyOf:
          - not:
              properties:
                call_to_action_media_url: {}
              required:
              - call_to_action_media_url
          - properties:
              call_to_action_media_url:
                type: 'null'
        - properties:
            double_opt_in:
              const: true
          required:
          - double_opt_in
          anyOf:
          - not:
              properties:
                double_opt_in_message: {}
              required:
              - double_opt_in_message
          - properties:
              double_opt_in_message:
                type: 'null'
    AgentLaunchCampaignConfiguration:
      allOf:
      - $ref: '#/components/schemas/AgentCampaignConfiguration'
      - type: object
        properties:
          agent_overview:
            type: string
            minLength: 1
            maxLength: 2000
          interactions:
            type: array
            minItems: 1
            items:
              $ref: '#/components/schemas/AgentInteraction'
          message_examples:
            type: array
            minItems: 3
            items:
              type: string
              minLength: 1
              maxLength: 2000
          consent_settings:
            $ref: '#/components/schemas/AgentConsentConfiguration'
        required:
        - agent_overview
        - interactions
        - message_examples
        - consent_settings
    ValidationErrorResponse:
      type: object
      properties:
        detail:
          type: array
          items:
            type: object
            properties:
              loc:
                type: array
                items:
                  oneOf:
                  - type: string
                  - type: integer
              msg:
                type: string
              type:
                type: string
            required:
            - loc
            - msg
            - type
      additionalProperties: true
      example:
        detail:
        - loc:
          - body
          - display_name
          msg: Field required
          type: missing
    TestDeviceResponse:
      type: object
      additionalProperties: false
      properties:
        test_device_id:
          type: string
          format: uuid
        phone_number:
          type: string
        invite_status:
          $ref: '#/components/schemas/TestDeviceInviteStatus'
      required:
      - test_device_id
      - phone_number
      - invite_status
      example:
        test_device_id: 44444444-4444-4444-8444-444444444444
        phone_number: '+13125550123'
        invite_status: ACCEPTED
    TestDeviceCreateRequest:
      type: object
      additionalProperties: false
      properties:
        phone_number:
          type: string
          maxLength: 16
          pattern: ^\+[1-9][0-9]{1,14}$
      required:
      - phone_number
      example:
        phone_number: '+13125550123'
    AgentPhoneContact:
      type: object
      additionalProperties: false
      properties:
        number:
          type: string
          maxLength: 16
          pattern: ^\+[1-9][0-9]{1,14}$
        label:
          type: string
          minLength: 1
          maxLength: 25
      required:
      - number
      - label
    AgentEmailContact:
      type: object
      additionalProperties: false
      properties:
        address:
          type: string
          format: email
          minLength: 3
          maxLength: 254
          pattern: ^[^@\s]+@[^@\s]+\.[^@\s]+$
        label:
          type: string
          minLength: 1
          maxLength: 25
      required:
      - address
      - label
    AgentWebsiteContact:
      type: object
      additionalProperties: false
      properties:
        url:
          $ref: '#/components/schemas/HttpUrl'
        label:
          type: string
          minLength: 1
          maxLength: 25
      required:
      - url
      - label
    AgentInteraction:
      type: object
      propertyNames:
        enum:
        - interaction_type
        - description
      properties:
        interaction_type:
          $ref: '#/components/schemas/AgentInteractionType'
        description:
          type:
          - string
          - 'null'
          minLength: 1
          maxLength: 2000
          description: Required when interaction_type is `OTHER`.
      required:
      - interaction_type
      allOf:
      - if:
          properties:
            interaction_type:
              const: OTHER
          required:
          - interaction_type
        then:
          properties:
            description:
              type: string
              minLength: 1
              maxLength: 2000
          required:
          - description
    AgentConfiguration:
      type: object
      additionalProperties: false
      properties:
        basics:
          $ref: '#/components/schemas/AgentBasicsConfiguration'
        campaign:
          oneOf:
          - $ref: '#/components/schemas/AgentCampaignConfiguration'
          - type: 'null'
        testing:
          oneOf:
          - $ref: '#/components/schemas/AgentTestingConfiguration'
          - type: 'null'
      required:
      - basics
  parameters:
    rcs-registration_IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: A caller-generated key containing letters, numbers, underscores, or hyphens. Reuse the same key and request body when retrying the same logical agent creation.
      schema:
        type: string
        minLength: 1
        maxLength: 255
        pattern: ^[A-Za-z0-9_-]+$
    AgentId:
      name: id
      in: path
      required: true
      description: The Telnyx-assigned agent identifier.
      schema:
        type: string
        format: uuid
    TestDeviceId:
      name: test_device_id
      in: path
      required: true
      description: The Telnyx-assigned test device identifier.
      schema:
        type: string
        format: uuid
  responses:
    DependencyUnavailable:
      description: A registration dependency is temporarily unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/rcs-registration_ErrorResponse'
    rcs-registration_NotFound:
      description: The resource does not exist, is not owned by the organization, or the provider does not support the requested capability.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/rcs-registration_ErrorResponse'
    rcs-registration_BadRequest:
      description: The request or idempotency header is malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/rcs-registration_ErrorResponse'
    ProviderError:
      description: The RCS provider rejected or could not complete the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/rcs-registration_ErrorResponse'
    ValidationError:
      description: The request body or parameters failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationErrorResponse'
    rcs-registration_Conflict:
      description: The operation is not allowed in the current lifecycle state or the idempotency key was used for a different request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/rcs-registration_ErrorResponse'
    rcs-registration_Unauthorized:
      description: The request is not authenticated.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/rcs-registration_ErrorResponse'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: 'Telnyx API key supplied as `Authorization: Bearer <token>`. In production, auth may be validated by the API gateway and forwarded via Telnyx auth headers.'
    Payment:
      type: apiKey
      in: header
      name: Authorization
      description: 'Machine Payment Protocol credential used on paid retries, sent as `Authorization: Payment ...`. Obtained by paying a challenge returned in the `WWW-Authenticate` header of a 402 response. This is not a Telnyx API key; initial challenge requests use standard bearer authentication instead.'
    agent-memory_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key
    bearerAuth:
      type: http
      scheme: bearer
    branded-calling_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
    collections_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Collections and results are automatically scoped to the authenticated user's organization.
    number-reputation_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
    oauthClientAuth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
        authorizationCode:
          authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
          tokenUrl: https://api.telnyx.com/v2/oauth/token
          refreshUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
      description: OAuth 2.0 authentication for Telnyx API and MCP integrations
    outbound-voice-profiles_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    pronunciation-dicts_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
    rcs-registration_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
    stored-payment-transactions_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    transcriptions-search_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Results are automatically scoped to the authenticated user's organization.
    web-search_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key
x-service-info:
  categories:
  - communication
  - developer-tools
  docs:
    apiReference: https://developers.telnyx.com
    homepage: https://telnyx.com
    llms: https://telnyx.com/llms.txt