Menu

Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Channels Resource

The Channel resource of Programmable Chat represents a "chat room" - a scope in which Messages can be sent and received.

Members can be added or invited to join channels. Channels exist within a Chat Service scope.

A list of a Users Channels can be retrieved which will return all the Channels the specified User is a Member of.

Channels can also have an optional, addressable Unique Name. This allows for a channel to be named something specific, and be looked up and addressed directly. The Unique Name is enforced as unique within the Service instance.

Twilio Console

You can view your Chat Channels using your Twilio console when logged in to the console. Within a Service, you will be able to browse the Channels within the Service.

Properties

Each channel has these properties:

Names in rb format
sid
sid<CH> Not PII

A 34 character string that uniquely identifies this resource.

account_sid
sid<AC> Not PII

The unique id of the Account responsible for this channel.

service_sid
sid<IS> Not PII

The unique id of the Service this channel belongs to.

friendly_name

The human-readable name of this channel. Optional.

unique_name

The unique, addressable name of this channel. Optional.

attributes

An optional string metadata field you can use to store any data you wish. The string value must contain structurally valid JSON if specified. Note that if the attributes are not set "{}" will be returned.

type
enum:channel_type Not PII

The visibility of this channel - either public or private

date_created
date_time<iso8601> Not PII

The date that this resource was created.

date_updated
date_time<iso8601> Not PII

The date that this resource was last updated.

created_by

Identity of the channel's creator. If the Channel was created through the API, the value will be system

members_count
integer Not PII

The number of Members in the Channel

messages_count
integer Not PII

The number of Messages in the Channel

url
url Not PII

An absolute URL for this channel.

links
uri_map Not PII

Absolute URLs to access the Members, Messages , Invites and, if it exists the last Message for this Channel.


List All Channels

GET /Services/{Service SID}/Channels
Names in rb format
service_sid
Required
get sid<IS> Not PII

Sid of the Service channel belongs to.

type
Optional
get enum:channel_type[] Not PII

The visibility of the channel - public or private. Defaults to public.

        
        
        
        

        Create a Channel

        POST /Services/{Service SID}/Channels
        

        Parameters

        Names in rb format
        service_sid
        Required
        post sid<IS> Not PII

        Sid of the Service this channel belongs to.

        friendly_name
        Optional
        post string PII MTL: 120 DAYS

        A human-readable name for the Channel. Optional.

        unique_name
        Optional
        post string PII MTL: 120 DAYS

        A unique, addressable name for the Channel. Optional.

        attributes
        Optional
        post string PII MTL: 120 DAYS

        An optional string metadata field you can use to store any data you wish. The string value must contain structurally valid JSON if specified. Note that if the attributes are not set "{}" will be returned.

        type
        Optional
        post enum:channel_type Not PII

        The visibility of the channel - public or private. Defaults to public.

        date_created
        Optional
        post date_time<iso8601> Not PII

        The optional ISO8601 time specifying the datetime the Channel should be set as being created. Will be set to the current time by the Chat service if not specified. Note that this should only be used in cases where a a Channel is being recreated from a backup/separate source

        date_updated
        Optional
        post date_time<iso8601> Not PII

        The optional ISO8601 time specifying the datetime the Channel should be set as having been last updated. Will be set to the null by the Chat service if not specified. Note that this should only be used in cases where a Channel is being recreated from a backup/separate source and where a Message was previously updated.

        created_by
        Optional
        post string PII MTL: 120 DAYS

        Optional field to specify the Identity of the User that created the Channel. Will be set to "system" if not specified.

        Notable Response Codes

        code description
        409 Conflict Channel with the specified unique name already exists
              
              
              
              

              Retrieve a Channel

              You are able to retrieve a Channel via the SID or UniqueName

              Channel SID

              GET /Services/{Service SID}/Channels/{Channel SID}
              

              UniqueName

              GET /Services/{Service SID}/Channels/{Unique Name}
              
                    
                    
                    
                    

                    Update a Channel

                    You are able to update a Channel via the SID or UniqueName

                    Channel SID

                    POST /Services/{Service SID}/Channels/{Channel SID}
                    

                    UniqueName

                    POST /Services/{Service SID}/Channels/{Unique Name}
                    

                    Parameters

                    Names in rb format
                    service_sid
                    Required
                    post sid<IS> Not PII

                    Sid of the Service this channel belongs to.

                    sid
                    Required
                    post sid_like<CH> Not PII

                    Key that uniquely defines the channel to fetch. Could be Sid or UniqueName

                    friendly_name
                    Optional
                    post string PII MTL: 120 DAYS

                    A human-readable name for the Channel. Optional.

                    unique_name
                    Optional
                    post string PII MTL: 120 DAYS

                    A unique, addressable name for the Channel. Optional.

                    attributes
                    Optional
                    post string PII MTL: 120 DAYS

                    An optional string metadata field you can use to store any data you wish. The string value must contain structurally valid JSON if specified. Note that if the attributes are not set "{}" will be returned.

                    date_created
                    Optional
                    post date_time<iso8601> Not PII

                    The optional ISO8601 time specifying the datetime the Channel should be set as being created.

                    date_updated
                    Optional
                    post date_time<iso8601> Not PII

                    The optional ISO8601 time specifying the datetime the Channel should be set as having been last updated.

                    created_by
                    Optional
                    post string PII MTL: 120 DAYS

                    Optional field to specify the Identity of the User that created the Channel.

                          
                          
                          
                          

                          Delete a Channel

                          You are able to delete a Channel via the SID or UniqueName

                          Channel SID

                          DELETE /Services/{Service SID}/Channels/{Channel SID}
                          

                          UniqueName

                          DELETE /Services/{Service SID}/Channels/{Unique Name}
                          
                                
                                
                                
                                

                                Need some help?

                                We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.