Skip to main content
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

HeaderValue
AuthorizationBearer
Content-Typeapplication/json

​
Body

​
type
string
required
The channel type to create. One of: webchat, widget, email, whatsapp, telegram, instagram, x, sms.
​
config
object
required
Channel-specific credentials and settings. Required fields differ by type — see the config reference below.
​
is_active
boolean
default:"true"
Whether the channel should be active immediately after creation.

​
Config reference by channel type

FieldTypeDescription
bot_tokenstringYour Telegram bot token from @BotFather. PingBack uses this to register a webhook automatically.
FieldTypeDescription
phone_number_idstringThe phone number ID from your Meta app.
access_tokenstringYour Meta permanent or long-lived access token.
verify_tokenstringA token you choose — used to verify the webhook during setup.
FieldTypeDescription
api_keystringX (Twitter) API key.
api_secretstringX API secret.
access_tokenstringAccess token for your X app.
access_token_secretstringAccess token secret.
bearer_tokenstringBearer token for read-only API access.

​
Response

​
id
string
required
UUID of the newly created channel.
​
business_id
string
required
UUID of the business that owns this channel.
​
type
string
required
The channel type.
​
config
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.
​
is_active
boolean
required
Whether the channel is active.
​
created_at
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
  }'

​
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

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

​
Delete a channel

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

​
Path parameters

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

​
Response example

{ "message": "Channel deleted" }

​
Errors

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