Channels

Refer to our channel definition for more information.

List#

POST /channels.list

Sample request

{
  "source": "source to filter on" // optional
}

Sample response

{
  "data": [
    {
      "id": "channel-uuid-1",
      "source": "facebook",
      "source_channel_id": "fb-page-id-1",
      "metadata": {
        "name": "my page 1",
        // optional
        "image_url": "http://example.org/avatar.jpeg"
      },
      "connected": true
    },
    {
      "id": "channel-uuid-2",
      "source": "facebook",
      "source_channel_id": "fb-page-id-2",
      "metadata": {
        "name": "my page 2"
      },
      "connected": true
    }
  ]
}

Info#

POST /channels.info

Sample request

{
  "channel_id": "channel-uuid"
}

Sample response

{
  "id": "channel-uuid",
  "source": "facebook",
  "source_channel_id": "fb-page-id-1",
  "metadata": {
    "name": "my page 1",
    // optional
    "image_url": "http://example.org/avatar.jpeg"
  },
  "connected": true
}

Update#

POST /channels.update

Update a channel's name or image URL.

Sample request

{
  "channel_id": "channel-uuid",
  "name": "new name for this channel", // optional
  "image_url": "http://example.org/avatar_redesign.jpeg" // optional
}

Sample response

{
  "id": "channel-uuid",
  "source": "facebook",
  "source_channel_id": "fb-page-id-1",
  "metadata": {
    "name": "new name for this channel",
    "image_url": "http://example.org/avatar_redesign.jpeg"
  },
  "connected": true
}

Connecting channels#

Airy Live Chat Plugin#

Connects a Chat Plugin source to Airy Core.

POST /channels.chatplugin.connect

name is a unique identifier of your choice.

{
  "name": "website-identifier-42",
  "image_url": "http://example.org/plugin_icon.jpeg" // optional
}

Sample response

{
  "id": "1f679227-76c2-4302-bb12-703b2adb0f66",
  "source": "chatplugin",
  "source_channel_id": "website-identifier-42",
  "metadata": {
    "name": "website-identifier-42",
    "image_url": "http://example.org/plugin_icon.jpeg" // optional
  },
  "connected": true
}

Facebook#

Connects a Facebook page to Airy Core.

POST /channels.facebook.connect

page_id is the Facebook page ID
page_token is the page Access Token
name is the custom name for the connected page
image_url is the custom image URL

Sample request

{
  "page_id": "fb-page-id-1",
  "page_token": "authentication token",
  "name": "My custom name for this page",
  "image_url": "https://example.org/custom-image.jpg" // optional
}

Sample response

{
  "id": "channel-uuid-1",
  "source": "facebook",
  "source_channel_id": "fb-page-id-1",
  "metadata": {
    "name": "My custom name for this page",
    // optional
    "image_url": "https://example.org/custom-image.jpg"
  }
}

Instagram#

Connects an Instagram account to Airy Core.

POST /channels.instagram.connect

page_id is ID of the Facebook page connected to the Instagram account
page_token is the Access Token of the Facebook page
account_id is the ID of the Instagram account
name is the custom name for the connected page
image_url (optional) is the custom image URL

Sample request

{
  "page_id": "fb-page-id-1",
  "account_id": "ig-account-id",
  "page_token": "authentication token",
  "name": "My custom name for this account",
  "image_url": "https://example.org/custom-image.jpg" // optional
}

Sample response

{
  "id": "channel-uuid-1",
  "source": "instagram",
  "source_channel_id": "ig-account-id",
  "metadata": {
    "name": "My custom name for this account",
    // optional
    "image_url": "https://example.org/custom-image.jpg"
  }
}

Facebook#

Connects a Whatsapp cloud phone number to Airy.

POST /channels.whatsapp.connect

phone_number_id the whatsapp phone number connected to your business account
user_token your user access token
name is the custom name for the connected page
image_url is a custom image url for displaying this channel on the UI

Sample request

{
  "phone_number_id": "1234567",
  "user_token": "user access token",
  "name": "Customer support hotline",
  "image_url": "https://example.org/custom-image.jpg" // optional
}

Sample response

{
  "id": "channel-uuid",
  "source": "whatsapp",
  "source_channel_id": "1234567",
  "metadata": {
    "name": "Customer support hotline",
    "image_url": "https://example.org/custom-image.jpg" // optional
  }
}

Google#

Connects a Google Business Account to Airy Core.

POST /channels.google.connect

gbm_id is the ID of your Google Business Message agent
name is the custom name for the connected business
image_url is the custom image URL

{
  "gbm_id": "gbm-id",
  "name": "My custom name for this location",
  "image_url": "https://example.com/custom-image.jpg" // optional
}

Sample response

{
  "id": "channel-uuid-1",
  "metadata": {"name": "My custom name for this location", "image_url": "https://example.com/custom-image.jpg"},
  "source": "google",
  "source_channel_id": "gbm-id"
}

SMS#

POST /channels.twilio.sms.connect

phone_number The phone number as listed in your Twilio dashboard. It must not contain spaces and must include the country code.
name is the custom name for the connected phone number
image_url is the custom image URL

Sample request

{
  phone_number: '+491234567',
  name: 'SMS for receipts',
  image_url: 'https://example.com/custom-image.jpg', // optional
}

Sample response

{
  id: 'channel-uuid-1',
  metadata: {name: 'SMS for receipts', image_url: 'https://example.com/custom-image.jpg'},
  source: 'twilio.sms',
  source_channel_id: '+491234567',
  connected: true,
}

Whatsapp#

POST /channels.twilio.whatsapp.connect

phone_number The phone number as listed in your Twilio dashboard. It must not have spaces and must include the country code.
name is the custom name for the connected phone number
image_url is the custom image URL

Sample request

{
  phone_number: '+491234567',
  name: 'WhatsApp Marketing',
  image_url: 'https://example.com/custom-image.jpg', // optional
}

Sample response

{
  id: 'channel-uuid-1',
  metadata: {name: 'WhatsApp Marketing', image_url: 'https://example.com/custom-image.jpg'},
  source: 'twilio.whatsapp',
  source_channel_id: 'whatsapp:+491234567',
  connected: true,
}

Disconnecting channels#

Airy Live Chat Plugin#

POST /channels.chatplugin.disconnect

A synchronous endpoint that makes a request to the source to disconnect the channel. It marks the channel as disconnected and deletes the auth token.

This action is idempotent, so if the channel is disconnected, the request returns status code 202. If the channel is unknown, the request returns status code 400.

Sample request

{
  channel_id: 'uuid',
}

Facebook#

Disconnects a Facebook page from Airy Core.

POST /channels.facebook.disconnect

A synchronous endpoint that makes a request to the source to disconnect the channel. It marks the channel as disconnected and deletes the auth token.

This action is idempotent, so if the channel is disconnected, the request returns status code 202. If the channel is unknown, the request returns status code 400.

Sample request

{
  channel_id: 'uuid',
}

Instagram#

Disconnects an instagram account from Airy Core.

POST /channels.instagram.disconnect

A synchronous endpoint that makes a request to the source to disconnect the channel. It marks the channel as disconnected and deletes the auth token.

This action is idempotent, so if the channel is disconnected, the request returns status code 202. If the channel is unknown, the request returns status code 400.

Sample request

{
  channel_id: 'uuid',
}

Google#

POST /channels.google.disconnect

A synchronous endpoint that makes a request to the source to disconnect the channel. It marks the channel as disconnected and deletes the auth token.

This action is idempotent, so if the channel is disconnected, the request returns status code 202. If the channel is unknown, the request returns status code 400.

Sample request

{
  channel_id: 'uuid',
}

SMS - Twilio#

POST /channels.twilio.sms.disconnect

A synchronous endpoint that makes a request to the source to disconnect the channel. It marks the channel as disconnected and deletes the auth token.

This action is idempotent, so if the channel is disconnected, the request returns status code 202. If the channel is unknown, the request returns status code 400.

Sample request

{
  channel_id: 'uuid',
}

Whatsapp - Twilio#

POST /channels.twilio.whatsapp.disconnect

A synchronous endpoint that makes a request to the source to disconnect the channel. It marks the channel as disconnected and deletes the auth token.

This action is idempotent, so if the channel is disconnected, the request returns status code 202. If the channel is unknown, the request returns status code 400.

Sample request

{
  channel_id: 'uuid',
}

Exploring available channels#

Facebook#

POST /channels.facebook.explore

A synchronous endpoint that makes a request to Facebook to list the available Facebook pages. Some of those pages may already be connected, which is accounted for in the boolean field connected. Due to the nature of the request, the response time may vary.

Sample request

{
  "auth_token": "authentication token"
}

Sample response

{
  "data": [
    {
      "name": "my page 1",
      "page_id": "fb-page-id-1",
      "connected": false,
      "image_url": "http://example.org/avatar.jpeg" // optional
    },
    {
      "name": "my page 2",
      "page_id": "fb-page-id-2",
      "connected": true
    }
  ]
}