Direct Message Channels

Direct message channels are typically used for ad-hoc and private communication between two or more users.

Get All DM Channels

Get information about all direct message channels.

GET /direct_message_channels

Pagination

The maximum number of channels that will be returned in a single request is 100. If there are more than 100 channels you can specify a page parameter great than 1 to get more data. The response will contain information about how many pages of data are available.

Query Parameters

Parameter

Default

Description

include_deleted

false

When true the response will include channels that have been marked for deletion.

include_users

false

When true the response will contain the list of users that are a members of each channel.

page

1

Specifies which page of results to return

per_page

100

Specifies maximum number of channels to return in a given request. The maximum you can specify is 100.

Success Response

A successful response will have an HTTP status of 200

Response Properties

Property

Description

page

Current page number of data returned

per_page

Maximum number of channels returned per page

total_pages

Number of pages of data available

response_count

The number of direct message channels that were returned from the given request

total_count

Total number of direct message channels that are available

channels

Collection of direct message channels

Example response

The sample response below indicates that you have received the second page of results. There are 2 pages available. The current page contains 21 of the total 121 channels.

{
    "page": 2,
    "per_page": 100,
    "total_pages": 2,
    "response_count": 21,
    "total_count": 121,
    "channels": [
      {...},
      {...}
    ]
}

Create Direct Message Channel

Create a new direct message channel.

POST direct_message_channels

Body Parameters

Parameter

Required

Default

Description

name

Yes

Name of the channel you are creating. This name must be unique. If there is already a channel with the name provided you will get a response with a 422 status.

is_tts_enabled

No

true

Specifies whether or no Text-To-Speech audio is enabled for the channel.

is_video_transcript_enabled

No

true

Specifies whether or no transcripts will be generated for video sessions in the channel.

users

Yes

Array of user objects. Each user object must contain and id. Example: [{id:123456}, {id: 98765}]

Direct Message Channels must contain at least 2 users

Example Request Body

{
    "name" : "Buddies", 
    "is_tts_enabled": false, 
    "users": [
        {"id": "d4fa7488-7a58-4bd0-956a-9f8c5b0a87f1"}, 
        {"id": "d13535e5-7ebf-4433-9fd1-90f3de9b6e2d"}, 
        {"id": "fdd21692-7d52-46b5-a01c-6d660a247a31"}
    ]
}

Success Response

A successful channel creation response will have an HTTP status of 201 created. The payload of the response is the same as you will see when requesting information about a specific channel.

Error Response

If there was a problem creating the channel you will receive a response that contains status and message properties.

Example error response:

{
    "status": 422,
    "message": {
        "error": "Direct Message Channel must contain at least 2 users."
    }
}

Get Specified Direct Message Channel

Get information about a specific direct message channel

GET /direct_message_channels/{channel_id}

Path Parameters

Parameter

Description

channel_id

Id of the channel you are requesting information about

Success Response

A successful channel creation response will have an HTTP status of 200

Response Properties

Property

Description

id

Unique channel identifier.

name

Name of the channel.

deleted

If true the channel has been marked for deletion.

is_tts_enabled

If true text to speech has been enabled for this channel.

is_video_transcript_enabled

If true transcription for video has been enabled for this channel.

users

Array of users that a member of the channel.

created_at

Date/time the channel was created.

updated_at

Date/time the channel was last updated.

Example Response Body

{
    "channel": {
        "id": "chat.groupdm.1a532a29-d207-44e2-a5e9-e70df67be311",
        "name": "Buddies",        
        "created_at": "2021-05-07T15:58:52.714Z",
        "updated_at": "2021-05-07T15:58:52.714Z",
        "is_tts_enabled": true,
        "is_video_transcript_enabled": true,
        "deleted": false,
        "users": [
            {
                "id": "d13535e5-7ebf-4433-9fd1-90f3de9b6e2d",
                "name": "Charlie Champ"
            },
            {
                "id": "d4fa7488-7a58-4bd0-956a-9f8c5b0a87f1",
                "name": "Victor Green"
            },
            {
                "id": "fdd21692-7d52-46b5-a01c-6d660a247a31",
                "name": "Tyler Lester"
            }
        ]
    }
}

Update Direct Message Channel

Update a specified direct message channel.

POST /direct_message_channels/{channel_id}

Path Parameters

Parameter

Description

channel_id

Id of the channel you are updating

Body Parameters

See Create DM Channel Body Parameters.

Success Response

A successful channel update response will have an HTTP status of 200. The payload of the response is the same as you will see when requesting information about a specific channel.

Soft Delete Direct Message Channel

Mark a specified direct message channel as deleted.

After you delete a channel it will not actually be removed from the platform. It will be flagged for deletion and will not appear in the ĀLO app.

DELETE /direct_message_channels/{channel_id}

Path Parameters

Parameter

Description

channel_id

Id of the channel you are deleting

Success Response

A successful channel soft delete will have an HTTP status of 200. The body of the response will also contain information about the channel that was deleted.

Hard Delete Direct Message Channel

Delete specified direct message channel.

After you hard delete a channel it WILL BE REMOVED from the platform. The channel and related information will not be recoverable.

DELETE /direct_message_channels/{channel_id}/hard_delete

Path Parameters

Parameter

Description

channel_id

Id of the channel you are deleting

Success Response

A successful channel hard delete will have an HTTP status of 200. The body of the response will also contain information about the channel that was deleted.

Last updated

Logo

© Copyright 2024 ALO.ai, Inc. • All Rights Reserved