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

# Create an Agent channel

> Connects a carrier number, SIP trunk, or WhatsApp endpoint to the named tenant-owned Agent under agents:write and channels:write. Provider onboarding has no idempotency key, so confirm an uncertain response before retrying.



## OpenAPI

````yaml https://api.getarbol.com/openapi.json post /agents/{agentId}/channels
openapi: 3.1.2
info:
  contact:
    email: support@getarbol.com
    name: Arbol
    url: https://docs.getarbol.com
  description: >-
    Provider-neutral API for creating and operating Arbol agents, contacts,
    conversations, channels, knowledge, integrations, and evaluations. Every
    request is bound to one Auth0 Organization.
  title: Arbol API
  version: 1.0.0
servers:
  - description: Production
    url: https://api.getarbol.com/v1
security: []
paths:
  /agents/{agentId}/channels:
    post:
      tags:
        - Channels
      summary: Create an Agent channel
      description: >-
        Connects a carrier number, SIP trunk, or WhatsApp endpoint to the named
        tenant-owned Agent under agents:write and channels:write. Provider
        onboarding has no idempotency key, so confirm an uncertain response
        before retrying.
      operationId: createAgentChannel
      parameters:
        - in: path
          required: true
          name: agentId
          schema:
            $ref: '#/components/schemas/ArbolResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                accountSid:
                  type: string
                  minLength: 1
                  maxLength: 160
                authToken:
                  type: string
                  minLength: 1
                  maxLength: 2000
                displayName:
                  type: string
                  minLength: 1
                  maxLength: 160
                kind:
                  anyOf:
                    - type: string
                      const: number
                    - type: string
                      const: sip
                    - type: string
                      const: whatsapp
                phoneNumber:
                  $ref: '#/components/schemas/E164PhoneNumber'
                mediaEncryption:
                  $ref: '#/components/schemas/SipMediaEncryption'
                  default: required
                password:
                  type: string
                  minLength: 1
                  maxLength: 2000
                terminationAddress:
                  type: string
                  minLength: 1
                  maxLength: 500
                transport:
                  $ref: '#/components/schemas/SipTransport'
                  default: tls
                username:
                  type: string
                  minLength: 1
                  maxLength: 255
              required:
                - kind
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAgentChannelResult'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
        '400':
          description: >-
            Inferable validation failure or a non-inferable malformed transport
            request.
          content:
            application/json:
              schema:
                oneOf:
                  - oneOf:
                      - $ref: '#/components/schemas/BadRequest'
                      - $ref: '#/components/schemas/UndefinedError'
                  - $ref: '#/components/schemas/TransportBadRequestError'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
        '401':
          description: Authentication is required.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/Unauthorized'
                  - $ref: '#/components/schemas/UndefinedError'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
        '403':
          description: The caller is not allowed to perform this operation.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/Forbidden'
                  - $ref: '#/components/schemas/UndefinedError'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
        '404':
          description: Agent not found
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/NotFound'
                  - $ref: '#/components/schemas/UndefinedError'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
        '409':
          description: The endpoint is already connected
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/Conflict3'
                  - $ref: '#/components/schemas/UndefinedError'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
        '413':
          $ref: '#/components/responses/TransportPayloadTooLarge'
        '415':
          $ref: '#/components/responses/TransportUnsupportedMediaType'
        '429':
          description: '429'
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/TooManyRequests'
                  - $ref: '#/components/schemas/UndefinedError'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
        '503':
          description: The channel provider is unavailable
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ServiceUnavailable'
                  - $ref: '#/components/schemas/UndefinedError'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
      security:
        - userOAuth:
            - org:use
            - agents:write
            - channels:write
        - machineOAuth:
            - agents:write
            - channels:write
components:
  schemas:
    ArbolResourceId:
      type: string
      maxLength: 64
      pattern: >-
        ^[a-z][a-z0-9]{1,15}_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
      description: >-
        Opaque Arbol resource identifier; the endpoint and tenant-scoped lookup
        determine its resource type.
      examples:
        - agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31
      title: Arbol resource ID
    E164PhoneNumber:
      type: string
      pattern: ^\+[1-9]\d{7,14}$
      description: International telephone number in E.164 form.
      examples:
        - '+573001234567'
      title: E.164 phone number
    SipMediaEncryption:
      type: string
      enum:
        - allowed
        - disabled
        - required
      description: Required media-encryption policy for a SIP channel.
      examples:
        - required
      title: SIP media encryption
    SipTransport:
      type: string
      enum:
        - auto
        - tcp
        - tls
        - udp
      description: Signaling transport requested for a SIP channel.
      examples:
        - tls
      title: SIP transport
    CreateAgentChannelResult:
      type: object
      properties:
        authorization:
          $ref: '#/components/schemas/AgentChannelAuthorization'
        channel:
          $ref: '#/components/schemas/AgentChannel'
      required:
        - channel
      additionalProperties: false
      description: >-
        Created channel plus a human setup capability when the provider requires
        one.
      title: Create Agent channel result
    BadRequest:
      type: object
      properties:
        defined:
          const: true
        inferable:
          type: boolean
        code:
          const: BAD_REQUEST
        status:
          const: 400
        message:
          type: string
        data:
          type: object
          properties:
            issues:
              maxItems: 20
              type: array
              items:
                type: object
                properties:
                  message:
                    type: string
                    maxLength: 500
                  path:
                    maxItems: 16
                    type: array
                    items:
                      anyOf:
                        - type: string
                          maxLength: 120
                        - type: integer
                          minimum: -9007199254740991
                          maximum: 9007199254740991
                required:
                  - message
                additionalProperties: false
            truncated:
              type: boolean
          required:
            - issues
            - truncated
          additionalProperties: false
      required:
        - defined
        - inferable
        - code
        - status
        - message
        - data
    UndefinedError:
      type: object
      properties:
        defined:
          const: false
        inferable:
          type: boolean
        code:
          type: string
        status:
          type: number
        message:
          type: string
        data: {}
      required:
        - defined
        - inferable
        - code
        - status
        - message
    TransportBadRequestError:
      additionalProperties: false
      properties:
        code:
          const: BAD_REQUEST
        data: {}
        defined:
          const: false
        inferable:
          const: false
        message:
          type: string
      required:
        - defined
        - inferable
        - code
        - message
      type: object
    Unauthorized:
      type: object
      properties:
        defined:
          const: true
        inferable:
          type: boolean
        code:
          const: UNAUTHORIZED
        status:
          const: 401
        message:
          type: string
        data: {}
      required:
        - defined
        - inferable
        - code
        - status
        - message
    Forbidden:
      type: object
      properties:
        defined:
          const: true
        inferable:
          type: boolean
        code:
          const: FORBIDDEN
        status:
          const: 403
        message:
          type: string
        data:
          type: object
          properties:
            missingPermissions:
              maxItems: 10
              type: array
              items:
                $ref: '#/components/schemas/AuthPermission'
          required:
            - missingPermissions
          additionalProperties: false
      required:
        - defined
        - inferable
        - code
        - status
        - message
    NotFound:
      type: object
      properties:
        defined:
          const: true
        inferable:
          type: boolean
        code:
          const: NOT_FOUND
        status:
          const: 404
        message:
          type: string
        data: {}
      required:
        - defined
        - inferable
        - code
        - status
        - message
    Conflict3:
      type: object
      properties:
        defined:
          const: true
        inferable:
          type: boolean
        code:
          const: CONFLICT
        status:
          const: 409
        message:
          type: string
        data: {}
      required:
        - defined
        - inferable
        - code
        - status
        - message
    TooManyRequests:
      type: object
      properties:
        defined:
          const: true
        inferable:
          type: boolean
        code:
          const: TOO_MANY_REQUESTS
        status:
          const: 429
        message:
          type: string
        data:
          type: object
          properties:
            retryAfterSeconds:
              type: integer
              exclusiveMinimum: 0
              maximum: 3600
          required:
            - retryAfterSeconds
          additionalProperties: false
      required:
        - defined
        - inferable
        - code
        - status
        - message
        - data
    ServiceUnavailable:
      type: object
      properties:
        defined:
          const: true
        inferable:
          type: boolean
        code:
          const: SERVICE_UNAVAILABLE
        status:
          const: 503
        message:
          type: string
        data: {}
      required:
        - defined
        - inferable
        - code
        - status
        - message
    AgentChannelAuthorization:
      type: object
      properties:
        expiresAt:
          $ref: '#/components/schemas/IsoDatetime'
        url:
          type: string
          maxLength: 4000
          format: uri
      required:
        - expiresAt
        - url
      additionalProperties: false
      description: >-
        Short-lived human authorization capability for completing provider
        channel setup.
      title: Agent channel authorization
    AgentChannel:
      type: object
      properties:
        address:
          anyOf:
            - type: string
              minLength: 1
              maxLength: 320
            - type: 'null'
        agentId:
          $ref: '#/components/schemas/ArbolResourceId'
        createdAt:
          $ref: '#/components/schemas/IsoDatetime'
        displayName:
          anyOf:
            - type: string
              minLength: 1
              maxLength: 160
            - type: 'null'
        id:
          $ref: '#/components/schemas/ArbolResourceId'
        inboundEnabled:
          type: boolean
        kind:
          $ref: '#/components/schemas/ManagedChannelKind'
        outboundEnabled:
          type: boolean
        status:
          $ref: '#/components/schemas/AgentChannelStatus'
        updatedAt:
          $ref: '#/components/schemas/IsoDatetime'
      required:
        - address
        - agentId
        - createdAt
        - displayName
        - id
        - inboundEnabled
        - kind
        - outboundEnabled
        - status
        - updatedAt
      additionalProperties: false
      description: Provider-neutral organization endpoint and its current Agent assignment.
      title: Agent channel
    AuthPermission:
      type: string
      enum:
        - agent-evaluations:read
        - agent-evaluations:run
        - agent-evaluations:write
        - agents:read
        - agents:write
        - analytics:read
        - arbi:use
        - channels:read
        - channels:write
        - contacts:read
        - contacts:write
        - conversations:read
        - conversations:transcript
        - conversations:write
        - definitions:read
        - definitions:write
        - facts:read
        - facts:write
        - integrations:read
        - integrations:write
        - knowledge:read
        - knowledge:write
        - org:manage
        - org:use
      description: >-
        One permission from the closed Arbol API vocabulary accepted from a
        verified Auth0 token.
      examples:
        - agents:read
      title: API permission
    TransportPayloadTooLargeError:
      additionalProperties: false
      properties:
        code:
          const: PAYLOAD_TOO_LARGE
        data: {}
        defined:
          const: false
        inferable:
          const: false
        message:
          type: string
      required:
        - defined
        - inferable
        - code
        - message
      type: object
    TransportUnsupportedMediaTypeError:
      additionalProperties: false
      properties:
        code:
          const: UNSUPPORTED_MEDIA_TYPE
        data: {}
        defined:
          const: false
        inferable:
          const: false
        message:
          type: string
      required:
        - defined
        - inferable
        - code
        - message
      type: object
    IsoDatetime:
      type: string
      format: date-time
      pattern: >-
        ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
      description: ISO 8601 timestamp with an explicit UTC offset.
      examples:
        - '2026-08-29T14:30:00Z'
      title: ISO timestamp
    ManagedChannelKind:
      type: string
      enum:
        - voice
        - whatsapp
      description: Channel type with an organization-managed provider endpoint.
      examples:
        - whatsapp
      title: Managed channel kind
    AgentChannelStatus:
      type: string
      enum:
        - pending
        - active
        - degraded
        - disabled
      description: Customer-visible lifecycle state of an Agent channel.
      examples:
        - active
      title: Agent channel status
  headers:
    RequestId:
      description: >-
        Opaque request correlation identifier. Include it when contacting Arbol
        support.
      schema:
        type: string
        maxLength: 128
  responses:
    TransportPayloadTooLarge:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TransportPayloadTooLargeError'
      description: The request body exceeds the API transport limit.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
    TransportUnsupportedMediaType:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TransportUnsupportedMediaTypeError'
      description: The request media type is not supported.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
  securitySchemes:
    userOAuth:
      description: >-
        Organization-scoped Auth0 user access token issued to an approved
        first-party client or exchanged by a trusted OBO resource server.
      flows:
        authorizationCode:
          authorizationUrl: https://auth.getarbol.com/authorize
          scopes:
            agent-evaluations:read: Read Agent evaluation suites, runs, and results.
            agent-evaluations:run: Execute and cancel Agent evaluation runs.
            agent-evaluations:write: Create and update Agent evaluation suites.
            agents:read: Read Agents and their explicitly requested expansions.
            agents:write: Create, update, and delete Agents.
            analytics:read: Read organization analytics.
            arbi:use: Use the personal Arbi workspace.
            channels:read: Read Agent channels.
            channels:write: Create, update, authorize, and delete Agent channels.
            contacts:read: Read Contacts and their explicitly requested expansions.
            contacts:write: Create, update, merge, import, and delete Contacts.
            conversations:read: Read Conversation metadata.
            conversations:transcript: Read Conversation messages and media evidence.
            conversations:write: Create and process Conversations.
            definitions:read: Read Definitions and Definition usage.
            definitions:write: Create, update, and retire Definitions.
            facts:read: Read current and historical Facts.
            facts:write: Assert typed Facts.
            integrations:read: Discover integrations, tools, accounts, and tool-bearing evidence.
            integrations:write: Authorize accounts and assign exact tool access.
            knowledge:read: Read Knowledge documents and search indexed content.
            knowledge:write: Create, index, update, and delete Knowledge documents.
            org:manage: Update the Organization and administer its members.
            org:use: Use Arbol as a member of the selected Auth0 Organization.
          tokenUrl: https://auth.getarbol.com/oauth/token
      type: oauth2
    machineOAuth:
      description: >-
        Organization-bound Auth0 client-credentials token. The client grant must
        contain every operation scope.
      flows:
        clientCredentials:
          scopes:
            agent-evaluations:read: Read Agent evaluation suites, runs, and results.
            agent-evaluations:run: Execute and cancel Agent evaluation runs.
            agent-evaluations:write: Create and update Agent evaluation suites.
            agents:read: Read Agents and their explicitly requested expansions.
            agents:write: Create, update, and delete Agents.
            analytics:read: Read organization analytics.
            channels:read: Read Agent channels.
            channels:write: Create, update, authorize, and delete Agent channels.
            contacts:read: Read Contacts and their explicitly requested expansions.
            contacts:write: Create, update, merge, import, and delete Contacts.
            conversations:read: Read Conversation metadata.
            conversations:transcript: Read Conversation messages and media evidence.
            conversations:write: Create and process Conversations.
            definitions:read: Read Definitions and Definition usage.
            definitions:write: Create, update, and retire Definitions.
            facts:read: Read current and historical Facts.
            facts:write: Assert typed Facts.
            integrations:read: Discover integrations, tools, accounts, and tool-bearing evidence.
            integrations:write: Authorize accounts and assign exact tool access.
            knowledge:read: Read Knowledge documents and search indexed content.
            knowledge:write: Create, index, update, and delete Knowledge documents.
            org:manage: Update the Organization and administer its members.
          tokenUrl: https://auth.getarbol.com/oauth/token
      type: oauth2

````