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

# Create Channel

> Connect a new messaging channel to your business.

Creates a new channel and registers the required webhooks or credentials with the external platform. After creation, PingBack automatically configures the integration (e.g., sets a Telegram webhook, stores Meta callback URLs for WhatsApp and Instagram).

**Method**: `POST`  **URL**: `/api/v1/channels/`

<Warning>
  Free plan accounts can only use the `widget` channel type. Omnichannel integrations (WhatsApp, Telegram, Instagram, X, SMS, Email) require a Mini or Pro plan.
</Warning>

### Headers

| Header        | Value            |
| ------------- | ---------------- |
| Authorization | Bearer {token}   |
| Content-Type  | application/json |

### Body

<ParamField body="type" type="string" required>
  The channel type to create. One of: `webchat`, `widget`, `email`, `whatsapp`, `telegram`, `instagram`, `x`, `sms`.
</ParamField>

<ParamField body="config" type="object" required>
  Channel-specific credentials and settings. Required fields differ by type — see the config reference below.
</ParamField>

<ParamField body="is_active" type="boolean" default="true">
  Whether the channel should be active immediately after creation.
</ParamField>

### Config reference by channel type

<AccordionGroup>
  <Accordion title="telegram">
    | Field       | Type   | Description                                                                                      |
    | ----------- | ------ | ------------------------------------------------------------------------------------------------ |
    | `bot_token` | string | Your Telegram bot token from @BotFather. PingBack uses this to register a webhook automatically. |
  </Accordion>

  <Accordion title="whatsapp / instagram">
    | Field             | Type   | Description                                                   |
    | ----------------- | ------ | ------------------------------------------------------------- |
    | `phone_number_id` | string | The phone number ID from your Meta app.                       |
    | `access_token`    | string | Your Meta permanent or long-lived access token.               |
    | `verify_token`    | string | A token you choose — used to verify the webhook during setup. |
  </Accordion>

  <Accordion title="x (Twitter)">
    | Field                 | Type   | Description                            |
    | --------------------- | ------ | -------------------------------------- |
    | `api_key`             | string | X (Twitter) API key.                   |
    | `api_secret`          | string | X API secret.                          |
    | `access_token`        | string | Access token for your X app.           |
    | `access_token_secret` | string | Access token secret.                   |
    | `bearer_token`        | string | Bearer token for read-only API access. |
  </Accordion>
</AccordionGroup>

### Response

<ResponseField name="id" type="string" required>
  UUID of the newly created channel.
</ResponseField>

<ResponseField name="business_id" type="string" required>
  UUID of the business that owns this channel.
</ResponseField>

<ResponseField name="type" type="string" required>
  The channel type.
</ResponseField>

<ResponseField name="config" type="object" required>
  The stored configuration. For WhatsApp and Instagram channels, PingBack appends a `_meta_setup_instructions` key containing the `callback_url` and `verify_token` you need to register in your Meta app dashboard.
</ResponseField>

<ResponseField name="is_active" type="boolean" required>
  Whether the channel is active.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  ISO 8601 timestamp of channel creation.
</ResponseField>

### Example

<CodeGroup>
  ```bash curl theme={null}
  curl --request POST \
    --url https://api.pingback.live/api/v1/channels/ \
    --header 'Authorization: Bearer {token}' \
    --header 'Content-Type: application/json' \
    --data '{
      "type": "telegram",
      "config": {
        "bot_token": "7123456789:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      },
      "is_active": true
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.pingback.live/api/v1/channels/', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer {token}',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      type: 'telegram',
      config: {
        bot_token: '7123456789:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
      },
      is_active: true
    })
  });

  const channel = await response.json();
  ```
</CodeGroup>

### Response example

```json theme={null}
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "business_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "type": "telegram",
  "config": {
    "bot_token": "7123456789:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  "is_active": true,
  "created_at": "2024-01-15T10:30:00Z"
}
```

***

## Update a channel

**Method**: `PATCH`  **URL**: `/api/v1/channels/{channel_id}`

Updates an existing channel's type, config, or active status. The same config rules by channel type apply.

### Path parameters

<ParamField path="channel_id" type="string" required>
  The UUID of the channel to update.
</ParamField>

### Body

Same fields as [Create Channel](#body): `type`, `config`, `is_active`.

### Example

<CodeGroup>
  ```bash curl theme={null}
  curl --request PATCH \
    --url https://api.pingback.live/api/v1/channels/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
    --header 'Authorization: Bearer {token}' \
    --header 'Content-Type: application/json' \
    --data '{
      "type": "telegram",
      "config": {
        "bot_token": "7123456789:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      },
      "is_active": false
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.pingback.live/api/v1/channels/3fa85f64-5717-4562-b3fc-2c963f66afa6',
    {
      method: 'PATCH',
      headers: {
        'Authorization': 'Bearer {token}',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        type: 'telegram',
        config: { bot_token: '7123456789:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxx' },
        is_active: false
      })
    }
  );

  const updated = await response.json();
  ```
</CodeGroup>

***

## Delete a channel

**Method**: `DELETE`  **URL**: `/api/v1/channels/{channel_id}`

Permanently removes a channel from your business. This cannot be undone.

### Path parameters

<ParamField path="channel_id" type="string" required>
  The UUID of the channel to delete.
</ParamField>

### Example

<CodeGroup>
  ```bash curl theme={null}
  curl --request DELETE \
    --url https://api.pingback.live/api/v1/channels/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
    --header 'Authorization: Bearer {token}'
  ```

  ```javascript JavaScript theme={null}
  await fetch(
    'https://api.pingback.live/api/v1/channels/3fa85f64-5717-4562-b3fc-2c963f66afa6',
    {
      method: 'DELETE',
      headers: { 'Authorization': 'Bearer {token}' }
    }
  );
  ```
</CodeGroup>

### Response example

```json theme={null}
{ "message": "Channel deleted" }
```

### Errors

| Status | Meaning                                                              |
| ------ | -------------------------------------------------------------------- |
| 400    | Bad request — missing required config fields or invalid channel type |
| 401    | Unauthorized — missing or invalid token                              |
| 402    | Plan limit reached — upgrade required to add this channel type       |
| 404    | Channel not found                                                    |