Create Channel

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/

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

Headers

Header	Value
Authorization	Bearer
Content-Type	application/json

Body

string

required

The channel type to create. One of: webchat, widget, email, whatsapp, telegram, instagram, x, sms.

object

required

Channel-specific credentials and settings. Required fields differ by type — see the config reference below.

boolean

default:"true"

Whether the channel should be active immediately after creation.

Config reference by channel type

Field	Type	Description
`bot_token`	string	Your Telegram bot token from @BotFather. PingBack uses this to register a webhook automatically.

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.

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.

Response

string

required

UUID of the newly created channel.

string

required

UUID of the business that owns this channel.

string

required

The channel 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.

boolean

required

Whether the channel is active.

string

required

ISO 8601 timestamp of channel creation.

Example

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
  }'

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();

Response example

{
  "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

string

required

The UUID of the channel to update.

Body

Same fields as Create Channel: type, config, is_active.

Example

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
  }'

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();

Delete a channel

Method: DELETE URL: /api/v1/channels/{channel_id} Permanently removes a channel from your business. This cannot be undone.

Path parameters

string

required

The UUID of the channel to delete.

Example

curl --request DELETE \
  --url https://api.pingback.live/api/v1/channels/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  --header 'Authorization: Bearer {token}'

await fetch(
  'https://api.pingback.live/api/v1/channels/3fa85f64-5717-4562-b3fc-2c963f66afa6',
  {
    method: 'DELETE',
    headers: { 'Authorization': 'Bearer {token}' }
  }
);

Response example

{ "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

Authentication

Conversations

Channels & Widget

Team

Knowledge Base

Analytics

Headers

Body

Config reference by channel type

Response

Example

Response example

Update a channel

Path parameters

Body

Example

Delete a channel

Path parameters

Example

Response example

Errors

​Headers

​Body

​Config reference by channel type

​Response

​Example

​Response example

​Update a channel

​Path parameters

​Body

​Example

​Delete a channel

​Path parameters

​Example

​Response example

​Errors

Headers

Body

Config reference by channel type

Response

Example

Response example

Update a channel

Path parameters

Body

Example

Delete a channel

Path parameters

Example

Response example

Errors