> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ada.cx/reference/conversations/create-channel/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server. # Create a new channel POST https://example.ada.support/api/v2/channels/ Content-Type: application/json Create a new channel. A maximum of 100 channels can be created per account per day. The maximum request size is 10MB. Reference: https://docs.ada.cx/reference/conversations/create-channel ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Body (application/json) This endpoint expects a CustomChannel. - `description` (string, required) — A description of the channel - `modality` (enum, required) — The modality of the channel - Allowed values: `messaging`, `email`, `voice`, `sms` - `name` (string, required) — The name of the channel - `capabilities` (BaseChannelCapabilities, optional) — What the channel's surface can render. The AI Agent tailors replies to the declared capabilities. Omitted fields default to false. Read-only on native channels, whose capabilities are fixed by the surface. - `created_at` (string, optional) — The date and time the channel was created - `id` (string, optional) — The channel ID - `metadata` (map from string to CustomChannelMetadata, optional) — A dictionary of key, value pairs assigned to the channel. Metadata may not exceed 4KB total. - `metadata` keys may only be of type: `string` - `metadata` values may only be one of type: `string`, `boolean`, `integer`, or `number` (float) - `type` (enum, optional) — The type of the channel - Allowed values: `custom` ## Response ### 201 Channel created - `description` (string, required) — A description of the channel - `modality` (enum, required) — The modality of the channel - Allowed values: `messaging`, `email`, `voice`, `sms` - `name` (string, required) — The name of the channel - `capabilities` (BaseChannelCapabilities, optional) — What the channel's surface can render. The AI Agent tailors replies to the declared capabilities. Omitted fields default to false. Read-only on native channels, whose capabilities are fixed by the surface. - `created_at` (string, optional) — The date and time the channel was created - `id` (string, optional) — The channel ID - `metadata` (map from string to CustomChannelMetadata, optional) — A dictionary of key, value pairs assigned to the channel. Metadata may not exceed 4KB total. - `metadata` keys may only be of type: `string` - `metadata` values may only be one of type: `string`, `boolean`, `integer`, or `number` (float) - `type` (enum, optional) — The type of the channel - Allowed values: `custom` ## Errors ### 400 Bad Request Error Bad Request - `errors` (list of ErrorsErrorsItems, required) — A list of errors ### 401 Unauthorized Error Unauthorized - `errors` (list of ErrorsErrorsItems, required) — A list of errors ### 413 Content Too Large Error Content Too Large - `errors` (list of ErrorsErrorsItems, required) — A list of errors ### 429 Too Many Requests Error Too Many Requests - `errors` (list of ErrorsErrorsItems, required) — A list of errors ### 500 Internal Server Error Internal Server Error - `errors` (list of ErrorsErrorsItems, required) — A list of errors ## Types ### BaseChannelCapabilities What the channel's surface can render. The AI Agent tailors replies to the declared capabilities. Omitted fields default to false. Read-only on native channels, whose capabilities are fixed by the surface. - `markdown` (boolean, optional, default: false) — Preserve Markdown (bold, italic, and links) in replies instead of flattening to plain text. - `quick_replies` (boolean, optional, default: false) — Deliver the tappable options of a Playbook Ask step as a `quick_replies` message instead of listing them in the reply's text. Applies to conversations created after the capability is set. Only a channel with the `messaging` modality can set it; the request is rejected on other modalities. Custom channels only: native channels always report false because Ada manages their message rendering. ### CustomChannelMetadata ### ErrorsErrorsItems - `type` (string, required) — The error type - `message` (string, required) — The error message - `details` (string, optional, nullable) — Extra information about the error ## Examples **Request** ```json { "description": "A custom messaging channel for my AI Agent", "modality": "messaging", "name": "My Custom Channel" } ``` **Response** ```json { "description": "A custom messaging channel for my AI Agent", "modality": "messaging", "name": "My Custom Channel", "capabilities": { "markdown": true, "quick_replies": true }, "created_at": "2020-09-20T00:00:00+00:00", "id": "5df263b7db5a7e6ea03fae9b", "metadata": { "example_key1": "example_string_value", "example_key2": true, "example_key3": 123, "example_key4": 0.95 }, "type": "custom" } ``` **SDK Code** ```python import requests url = "https://example.ada.support/api/v2/channels/" payload = { "description": "A custom messaging channel for my AI Agent", "modality": "messaging", "name": "My Custom Channel" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://example.ada.support/api/v2/channels/'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"description":"A custom messaging channel for my AI Agent","modality":"messaging","name":"My Custom Channel"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://example.ada.support/api/v2/channels/" payload := strings.NewReader("{\n \"description\": \"A custom messaging channel for my AI Agent\",\n \"modality\": \"messaging\",\n \"name\": \"My Custom Channel\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://example.ada.support/api/v2/channels/") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"description\": \"A custom messaging channel for my AI Agent\",\n \"modality\": \"messaging\",\n \"name\": \"My Custom Channel\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://example.ada.support/api/v2/channels/") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"description\": \"A custom messaging channel for my AI Agent\",\n \"modality\": \"messaging\",\n \"name\": \"My Custom Channel\"\n}") .asString(); ``` ```php request('POST', 'https://example.ada.support/api/v2/channels/', [ 'body' => '{ "description": "A custom messaging channel for my AI Agent", "modality": "messaging", "name": "My Custom Channel" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://example.ada.support/api/v2/channels/"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"description\": \"A custom messaging channel for my AI Agent\",\n \"modality\": \"messaging\",\n \"name\": \"My Custom Channel\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "description": "A custom messaging channel for my AI Agent", "modality": "messaging", "name": "My Custom Channel" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://example.ada.support/api/v2/channels/")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```