Communication Channels API

API for accessing users' email addresses, SMS phone numbers, Twitter, and Yo communication channels.

In this API, the :user_id parameter can always be replaced with self if the requesting user is asking for his/her own information.

A CommunicationChannel object looks like:

{
  // The ID of the communication channel.
  "id": 16,
  // The address, or path, of the communication channel.
  "address": "sheldon@caltech.example.com",
  // The type of communcation channel being described. Possible values are: 'email',
  // 'push', 'sms', 'twitter' or 'yo'. This field determines the type of value seen
  // in 'address'.
  "type": "email",
  // The position of this communication channel relative to the user's other channels
  // when they are ordered.
  "position": 1,
  // The ID of the user that owns this communication channel.
  "user_id": 1,
  // The current state of the communication channel. Possible values are:
  // 'unconfirmed' or 'active'.
  "workflow_state": "active"
}

List user communication channels CommunicationChannelsController#index

GET /api/v1/users/:user_id/communication_channels

Returns a list of communication channels for the specified user, sorted by position.

Example Request:

curl https://<canvas>/api/v1/users/12345/communication_channels \
     -H 'Authorization: Bearer <token>'
Returns a list of CommunicationChannels

Create a communication channel CommunicationChannelsController#create

POST /api/v1/users/:user_id/communication_channels

Creates a new communication channel for the specified user.

Request Parameters:

Parameter Type Description
communication_channel[address] Required string

An email address or SMS number. Not required for “push” type channels.
communication_channel[type] Required string

The type of communication channel.

In order to enable push notification support, the server must be properly configured (via sns.yml) to communicate with Amazon Simple Notification Services, and the developer key used to create the access token from this request must have an SNS ARN configured on it.

Allowed values: email, sms, push

communication_channel[token] string

A registration id, device token, or equivalent token given to an app when registering with a push notification provider. Only valid for “push” type channels.
skip_confirmation boolean

Only valid for site admins and account admins making requests; If true, the channel is automatically validated and no confirmation email or SMS is sent. Otherwise, the user must respond to a confirmation message to confirm the channel.

Example Request:

curl https://<canvas>/api/v1/users/1/communication_channels \
     -H 'Authorization: Bearer <token>' \
     -d 'communication_channel[address]=new@example.com' \
     -d 'communication_channel[type]=email' \
Returns a CommunicationChannel

Delete a communication channel CommunicationChannelsController#destroy

DELETE /api/v1/users/:user_id/communication_channels/:id

DELETE /api/v1/users/:user_id/communication_channels/:type/:address

Delete an existing communication channel.

Example Request:

curl https://<canvas>/api/v1/users/5/communication_channels/3
     -H 'Authorization: Bearer <token>
     -X DELETE
Returns a CommunicationChannel