> ## 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 the Agent channel > Connects a carrier number, SIP trunk, or WhatsApp endpoint for the verified Organization under agents:write and channels:write. Omit agentId to connect it unassigned and attach an Agent later; several endpoints may route to the same Agent. Provider onboarding has no idempotency key, so confirm an uncertain response before retrying. ## OpenAPI ````yaml https://api.getarbol.com/openapi.json post /channels openapi: 3.1.2 info: contact: email: support@getarbol.com name: Arbol url: https://docs.getarbol.com description: >- Build and operate Arbol's organization-scoped conversational platform through one provider-neutral REST contract. Resources cover Agents, channels, contacts, conversations, Knowledge, connected accounts, analytics, and evaluation runs. Every bearer is verified by Auth0, every request is bound to exactly one Organization, and every operation enforces all scopes listed in its security requirement. title: Arbol API version: 1.0.0 servers: - description: Production url: https://api.getarbol.com/v1 security: [] tags: - description: >- Create and configure conversational Agents. Provider-specific runtime details remain private to Arbol. name: Agents - description: >- Define suites, start durable evaluation runs, inspect trials, and compare Agent behavior. name: Agent evaluations - description: >- Read organization-scoped operational aggregates without exposing raw provider telemetry. name: Analytics - description: >- Attach and manage provider-neutral voice or messaging endpoints owned by an Agent. name: Channels - description: >- Authorize and manage reusable organization accounts whose credentials remain in Composio. name: Connected accounts - description: >- Manage people, their routable identities, merged activity timeline, and durable CSV imports. name: Contacts - description: >- Start outbound calls and inspect tenant-scoped voice, WhatsApp, and web conversations. name: Conversations - description: >- Define revisioned structured fields used to capture organization-specific Contact and Conversation facts. name: Definitions - description: >- Call a list of phone numbers with one Agent, a few at a time, with optional first-message and prompt overrides. name: Outbound batches - description: >- Read and assert typed values against active Definitions with explicit evidence and verification state. name: Facts - description: >- Discover live business-tool capabilities available through Arbol's Composio boundary. name: Integrations - description: >- Upload, index, search, download, and lifecycle-manage organization Knowledge documents. name: Knowledge - description: Read and update the current Organization's product-level settings. name: Organization - description: >- Discover provider-neutral synthetic voices that can be assigned to voice Agents. name: Voices paths: /channels: post: tags: - Channels summary: Create the Agent channel description: >- Connects a carrier number, SIP trunk, or WhatsApp endpoint for the verified Organization under agents:write and channels:write. Omit agentId to connect it unassigned and attach an Agent later; several endpoints may route to the same Agent. Provider onboarding has no idempotency key, so confirm an uncertain response before retrying. operationId: createAgentChannel requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAgentChannelInput' 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 provider endpoint already has a live channel 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/ServiceUnavailable2' - $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: CreateAgentChannelInput: oneOf: - $ref: '#/components/schemas/CreateNumberAgentChannelInput' - $ref: '#/components/schemas/CreateSipAgentChannelInput' - $ref: '#/components/schemas/CreateWhatsAppAgentChannelInput' description: >- Provider-specific onboarding input for one organization endpoint. Omit agentId to connect it unassigned and attach an Agent later. title: Create Agent channel input 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: code: type: string enum: - custom - invalid_format - invalid_type - invalid_value - too_big - too_small - unrecognized_keys message: type: string maxLength: 500 path: maxItems: 16 type: array items: anyOf: - type: string maxLength: 120 - type: integer minimum: 0 maximum: 9007199254740991 required: - code - 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 ServiceUnavailable2: 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 CreateNumberAgentChannelInput: type: object properties: accountSid: type: string minLength: 1 maxLength: 160 agentId: $ref: '#/components/schemas/ArbolResourceId' authToken: type: string minLength: 1 maxLength: 2000 displayName: type: string minLength: 1 maxLength: 160 kind: type: string const: number phoneNumber: $ref: '#/components/schemas/E164PhoneNumber' required: - accountSid - authToken - kind - phoneNumber additionalProperties: false description: Connects a managed voice number as an Agent channel. title: Create number channel input CreateSipAgentChannelInput: type: object properties: agentId: $ref: '#/components/schemas/ArbolResourceId' displayName: type: string minLength: 1 maxLength: 160 kind: type: string const: sip mediaEncryption: $ref: '#/components/schemas/SipMediaEncryption' default: required password: type: string minLength: 1 maxLength: 2000 phoneNumber: $ref: '#/components/schemas/E164PhoneNumber' terminationAddress: type: string minLength: 1 maxLength: 500 transport: $ref: '#/components/schemas/SipTransport' default: tls username: type: string minLength: 1 maxLength: 255 required: - kind - phoneNumber - terminationAddress additionalProperties: false description: >- Imports a carrier number over a SIP trunk; trunk credentials are handed to the provider and never stored. title: Create SIP channel input CreateWhatsAppAgentChannelInput: type: object properties: agentId: $ref: '#/components/schemas/ArbolResourceId' kind: type: string const: whatsapp required: - kind additionalProperties: false description: >- Starts a WhatsApp channel whose setup completes through the returned authorization. title: Create WhatsApp channel input 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: anyOf: - $ref: '#/components/schemas/ArbolResourceId' - type: 'null' 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 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 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 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 ````