> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update calling routing for a phone number

> Set or clear the connection that inbound WhatsApp calls to a BYON (Bring Your Own Number) phone number are delivered to.

The update is processed asynchronously. A `202` response means the request was accepted, not that the routing changed. Check the result with `GET /whatsapp/phone_numbers/{id}/calling_routing`, which can return the previous value immediately after an update. An update for a number that is not a WhatsApp Calling number in the account returns 404.

The connection must belong to the same account and must not be a WhatsApp connection. Send `connection_id: null` to clear the routing; omitting `connection_id` is rejected. Numbers active on Telnyx are rejected, because they route through their own connection assignment.

Sub-users need update permission on connections, and read permission to check the result with `GET`.



## OpenAPI

````yaml /openapi/source/external/legacy-published/whatsapp/management.json patch /whatsapp/phone_numbers/{id}/calling_routing
openapi: 3.1.0
info:
  contact:
    email: support@telnyx.com
  description: >
    API for managing WhatsApp Business Accounts (WABAs), phone numbers, and
    message templates.


    Use these endpoints to:

    - List and manage WhatsApp Business Accounts

    - Configure phone numbers for WhatsApp

    - Create and manage message templates

    - Set up webhook configurations
  title: Telnyx WhatsApp Management API
  version: 2.0.0
servers:
  - url: https://api.telnyx.com/v2
security:
  - bearerAuth: []
paths:
  /whatsapp/phone_numbers/{id}/calling_routing:
    patch:
      tags:
        - Whatsapp Phone Numbers
      summary: Update calling routing for a phone number
      description: >-
        Set or clear the connection that inbound WhatsApp calls to a BYON (Bring
        Your Own Number) phone number are delivered to.


        The update is processed asynchronously. A `202` response means the
        request was accepted, not that the routing changed. Check the result
        with `GET /whatsapp/phone_numbers/{id}/calling_routing`, which can
        return the previous value immediately after an update. An update for a
        number that is not a WhatsApp Calling number in the account returns 404.


        The connection must belong to the same account and must not be a
        WhatsApp connection. Send `connection_id: null` to clear the routing;
        omitting `connection_id` is rejected. Numbers active on Telnyx are
        rejected, because they route through their own connection assignment.


        Sub-users need update permission on connections, and read permission to
        check the result with `GET`.
      operationId: updateWhatsappCallingRouting
      parameters:
        - $ref: '#/components/parameters/WhatsappCallingRoutingNumber'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WhatsappPatchCallingRoutingRequest'
            examples:
              set:
                summary: Route the number to a connection
                value:
                  connection_id: '1234567890'
              clear:
                summary: Clear the routing
                value:
                  connection_id: null
      responses:
        '202':
          description: >-
            Update accepted for processing. The body echoes the requested
            routing; it does not confirm that the routing was applied.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/WhatsappCallingRoutingData'
                required:
                  - data
              examples:
                set:
                  summary: Routing update accepted
                  value:
                    data:
                      record_type: whatsapp_calling_routing
                      phone_number: '+13125550100'
                      connection_id: '1234567890'
                clear:
                  summary: Routing clear accepted
                  value:
                    data:
                      record_type: whatsapp_calling_routing
                      phone_number: '+13125550100'
                      connection_id: null
        '403':
          description: >-
            The caller is not permitted to perform this action. Sub-users need
            update permission on connections.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messaging_Errors'
              example:
                errors:
                  - code: '10010'
                    title: Authorization failed
                    detail: >-
                      You do not have permission to perform the requested action
                      on the specified resource or resources.
        '404':
          description: >-
            The account has no WhatsApp Calling number with this phone number,
            or the requesting account could not be found. A number just enabled
            for WhatsApp Calling returns 404 until it is provisioned, so retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messaging_Errors'
              example:
                errors:
                  - code: '10003'
                    title: Resource not found
                    detail: The requested resource or URL could not be found.
        '422':
          description: >-
            Validation failed. Errors are keyed by field: `phone_number` when
            the number is not valid E.164 or is active on Telnyx, and
            `connection_id` when it is missing, is not a positive integer ID, is
            not a connection in the account, or is a WhatsApp connection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WhatsappCallingRoutingFieldErrors'
              examples:
                invalid_phone_number:
                  summary: Phone number is not valid E.164
                  value:
                    errors:
                      phone_number:
                        - is not a valid E.164 phone number
                telnyx_number:
                  summary: Phone number is active on Telnyx
                  value:
                    errors:
                      phone_number:
                        - is a Telnyx number and routes via its own assignment
                missing_connection_id:
                  summary: connection_id omitted from the body
                  value:
                    errors:
                      connection_id:
                        - is required
                invalid_connection_id:
                  summary: >-
                    connection_id is malformed or not a connection in the
                    account
                  value:
                    errors:
                      connection_id:
                        - is invalid
                whatsapp_connection:
                  summary: connection_id is a WhatsApp connection
                  value:
                    errors:
                      connection_id:
                        - cannot be a WhatsApp connection
        '503':
          description: >-
            The update could not be confirmed as queued for processing, so it
            may or may not be applied. The request can be retried.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WhatsappCallingRoutingFieldErrors'
              example:
                errors:
                  event:
                    - could not be published
        4XX:
          $ref: '#/components/responses/messaging_GenericErrorResponse'
components:
  parameters:
    WhatsappCallingRoutingNumber:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: The BYON phone number in E.164 format. The leading `+` is optional.
      example: '+13125550100'
  schemas:
    WhatsappPatchCallingRoutingRequest:
      type: object
      required:
        - connection_id
      properties:
        connection_id:
          type:
            - string
            - integer
            - 'null'
          description: >-
            ID of the connection to deliver inbound WhatsApp calls to: a
            positive integer up to 9223372036854775807, sent as a decimal string
            or an integer. Send a string to keep large IDs exact. Non-null
            values are returned as strings. `null` clears the routing.
          example: '1234567890'
    WhatsappCallingRoutingData:
      type: object
      properties:
        record_type:
          type: string
          enum:
            - whatsapp_calling_routing
          description: Identifies the type of the resource.
          example: whatsapp_calling_routing
        phone_number:
          type: string
          description: Phone number in E.164 format, with a leading `+`.
          example: '+13125550100'
        connection_id:
          type:
            - string
            - 'null'
          description: ID of the routing connection, or `null` when none is set.
          example: '1234567890'
      required:
        - record_type
        - phone_number
        - connection_id
    messaging_Errors:
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/messaging_Error'
    WhatsappCallingRoutingFieldErrors:
      type: object
      properties:
        errors:
          type: object
          description: Error messages keyed by the field or step that failed.
          additionalProperties:
            type: array
            items:
              type: string
      required:
        - errors
    messaging_Error:
      required:
        - code
        - title
      properties:
        code:
          type: string
          x-format: integer
        title:
          type: string
        detail:
          type: string
        source:
          type: object
          properties:
            pointer:
              description: JSON pointer (RFC6901) to the offending entity.
              type: string
              format: json-pointer
            parameter:
              description: Indicates which query parameter caused the error.
              type: string
        meta:
          type: object
  responses:
    messaging_GenericErrorResponse:
      description: Unexpected error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/messaging_Errors'
          example:
            errors:
              - code: string
                title: string
                detail: string
                source:
                  pointer: /data/attributes/phone_number
                  parameter: string
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http

````