Introduction
This is the official Twist API v3 documentation, a reference to the functionality our public API provides, with detailed description of each API endpoint, its parameters, and examples.
Authentication
Login and signup are done via /api/v3/users/login and /api/v3/users/register. For public integration, you must use our OAuth 2 authentication.
If you just want a token to try the API, we provide a test token when you create an application following what we describe in the OAuth 2 authentication guide.
Temporary ids
Temporary ids are negative and can be used when adding, updating or deleting items.
Request, response, and error handling
The maximum allowed size of the request body for common requests is 5MB. Some attachments have their own limits for upload, please check their own sections for more details.
A response is always a JSON object which can be the following:
- On successful return: JSON data.
- On an error return, HTTP error code followed by:
{βerrorβ: [error_code, error_string], **kwargs}
.
Dates
For dates we use ISO 8601. The formatting we can have inside the system:
- Date time:
%Y-%m-%d %H:%M:%S
. - Date only:
%Y-%m-%d
. - With timezone info:
%Y-%m-%d %H:%M:%S +00:00
.
The current API should only return %Y-%m-%d %H:%M:%S
, where the time zone is
implicit set to UTC
.
Errors
Errors will be returned as JSON objects.
Example of error JSON object
{
"error_uuid": "f699b0e0caa4446e847e17cc1d42801b",
"error_code": 200,
"error_extra": { },
"error_string": "Invalid token"
}
The errors returned:
Error code | Error explanation | HTTP status code |
---|---|---|
19 | Required argument is missing. | 400 |
20 | Invalid argument value. | 400 |
101 | Your email is already found in our database. | 400 |
102 | Password too short. | 400 |
103 | Email is invalid. | 400 |
104 | Email or password are invalid. | 400 |
105 | Workspace not found. | 404 |
106 | User not found. | 404 |
107 | Channel not found. | 404 |
108 | Thread not found. | 404 |
109 | Forbidden. | 403 |
110 | Resource not found. | 404 |
111 | Unknown temp id. | 404 |
112 | Invalid temp id. | 400 |
113 | Temp id already found. | 400 |
114 | Bad Request. | 400 |
115 | Comment not found. | 404 |
116 | Device not found. | 404 |
117 | Search not available. | 404 |
118 | One or more attachments don’t comply with the JSON specification. | 400 |
119 | Group not found. | 404 |
120 | You are not logged in. | 401 |
121 | Invalid timezone. | 401 |
122 | Not supported reaction. | 401 |
124 | Conversation not found. | 404 |
125 | Message not found. | 404 |
126 | Your name is too short. | 400 |
127 | You can’t remove the last admin. | 400 |
128 | Invalid date range. | 400 |
129 | Google account is not connected to any Twist user. | 404 |
130 | Google account is already connected to a Google user. | 403 |
131 | Already found. | 409 |
132 | Email not found. | 404 |
133 | One or more actions don’t comply with the JSON specification. | 404 |
200 | Invalid token. | 403 |
201 | Internal Server Error. | 500 |
202 | Upload failed. | 400 |
203 | Payment required. | 402 |
204 | External Server Error. | 500 |
205 | Upload is too big in size. | 413 |
406 | Not acceptable. | 406 |
The HTTP error codes returned:
Status code | Description |
---|---|
400 | Bad Request. |
401 | Access Denied (token invalid, the user needs to login). |
403 | Forbidden. |
404 | Not found. |
406 | Not acceptable. |
500 | Internal Server Error. |
Testing error handling
To test error handling simply provide ?chaos=random
as an argument. If you
want to test a specific error you can supply ?chaos=109
.
Authentication
In order to make authorized calls to Twist APIs, your integration must first obtain an access token from the users. This section describes how to obtain such a token.
OAuth 2
Before getting started, you need to create a general integration and configure a valid OAuth redirect URL. A registered Twist integration is assigned a unique Client ID and Client Secret which are needed for the OAuth2 flow.
The OAuth integration page also has a test token for those who just want to try the API out whilst in development. The test token provided may be used in any requests requiring authorization. The test token will use the current authenticated user account to authorize the utilization of the resources.
When building an integration, it’s necessary to ask the user’s permission to use the resources and for that you have to do the 3 steps procedure described below.
All the error responses will be in JSON format, an example is
{"error":"BAD_REQUEST", "error_message": "Invalid scope"}
.
Step 1: The authorization request
Redirect users to the authorization URL at the endpoint
https://twist.com/oauth/authorize
, with the specified request parameters.
Here follow the required parameters:
Name | Description |
---|---|
client_id | The unique Client ID of the Twist integration that you registered. |
scope | A comma separated list of permissions that you would like the users to grant to your integration. See below a table with more details about this. |
state | A unique and unguessable string. It is used to protect you against cross-site request forgery attacks. |
And here are some common errors that you may encounter (you will find more info in error.error_message
):
Error | Description |
---|---|
ACCESS_DENIED | When the user denies your authorization request, Twist will redirect the user to the configured redirect URI with the error parameter: http://example.com?error=ACCESS_DENIED . |
FORBIDDEN | A permissions issue happened. |
BAD_REQUEST | The request was badly formatted, for example, if you supply an invalid scope . |
Step 2: The redirection to your integration site
When the user grants your authorization request, the user will be redirected to
the redirect URL configured in your integration setting. The redirect request
will come with two query parameters attached: code
and state
.
The code
parameter contains the authorization code that you will use to
exchange for an access token. The state parameter should match the state
parameter that you supplied in the previous step. If the state is unmatched,
your request has been compromised by other parties, and the process should be
aborted.
Step 3: The redirection to your integration site
Once you have the authorization code
, you can exchange it for the access token
at the endpoint POST https://twist.com/oauth/access_token
.
Name | Description |
---|---|
client_id | The unique Client ID of the Twist integration that you registered. |
client_secret | The unique Client Secret of the Twist integration that you registered. |
code | The unique string code that you obtained in the previous step. |
Scopes
These are the scope permissions that the user grant your integration:
Name | Description |
---|---|
user:write | Access and update user’s personal settings. |
user:read | Access user’s personal settings. |
workspaces:write | Access and update teams the user is part of. |
workspaces:read | Access teams the user is part of. |
channels:remove | Access, update, and delete channels. |
channels:write | Access and update channels. |
channels:read | Access channels. |
threads:remove | Access, update, and delete threads. |
threads:write | Access and update threads. |
threads:read | Access threads. |
comments:remove | Access, update, and delete comments. |
comments:write | Access and update comments. |
comments:read | Access comments. |
groups:remove | Access, update, and delete groups. |
groups:write | Access and update groups. |
groups:read | Access groups. |
messages:remove | Access, update, and delete messages. |
messages:write | Access and update messages. |
messages:read | Access messages. |
reactions:remove | Access, update, and delete reactions. |
reactions:write | Access and update reactions. |
reactions:read | Access reactions. |
search:read | Search. |
attachments:write | Access and update attachments. |
attachments:read | Access attachments. |
notifications:write | Read and update user’s notifications settings. |
notifications:read | Read user’s notifications settings. |
Batching requests
Example
$ curl -X POST https://api.twist.com/api/v3/batch \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d requests='[{"method": "GET", "url": "https://api.twist.com/api/v3/workspaces/get?token=..."},
{"method": "GET", "url": "https://api.twist.com/api/v3/workspaces/getone?token=...&id=201"}]'
POST /api/v3/batch
Batching allows you to pass several requests in a single HTTP request. Once all operations have been completed, a consolidated response will be passed back to you and the HTTP connection will be closed.
Return object
[
{
"code": 200,
"headers": "...",
"body": "..."
},
{
"code": 200,
"headers": "...",
"body": "..."
}
]
Parameters
Name | Required | Description |
---|---|---|
requests List of Objects | Yes | The requests to send. |
requests[“method”] String | Yes | The HTTP method like GET or POST . |
requests[“url”] String | Yes | The completed URL with any arguments needed. |
Users
A user represents a real person who collaborates with other users.
User object:
{
"scheduled_banners": [
"notification_permissions"
],
"short_name": "User",
"contact_info": "",
"bot": false,
"profession": "",
"snooze_dnd_start": null,
"client_id": "9ea8c3de-349e-11e7-976e-06b24c4507db",
"timezone": "UTC",
"removed": false,
"avatar_id": "c5f14f4da3ee2479a26c65c630c21765",
"id": 10073,
"comet_channel": "10073-15c9c64dae211c526c77164d31dd5b6e9eabcdda",
"lang": "en",
"away_mode": {
"date_from": "2018-08-09",
"type": "other",
"date_to": "2018-08-10"
},
"first_name": "User",
"comet_server": "https://comet.twist.com",
"name": "User",
"off_days": [],
"restricted": false,
"default_workspace": 5517,
"token": "9b1bf97783c1ad5593dee12f3019079dbd3042cf",
"snooze_dnd_end": null,
"snoozed": false,
"email": "user@example.com",
"setup_pending": false,
"snooze_until": -1,
}
Properties of user object
Name | Description |
---|---|
scheduled_banners List of Strings | A list of banners to be shown to the user. |
short_name String | The user’s short name. |
contact_info String | The user’s contact info. |
bot Boolean | Whether user is a bot. |
profession String | The user’s profession. |
snooze_dnd_start String | Start time of do-not-disturb snooze for notifications. |
client_id String | The user’s client id |
timezone String | The user’s timezone. |
removed Boolean | Whether the user has been removed. |
avatar_id String | The user’s avatar id. |
id Integer | The id of the user. |
comet_channel String | The comet channel. |
lang String | The user’s language. |
away_mode Object | Away mode sets the user as away until some future date. |
away_mode#type String | The reason of being in away mode may be parental , vacation , sickleave , or other . |
away_mode#date_from String | The start date of the away mode in a %Y-%m-%d format. The date_from parameter is inclusive. optional. |
away_mode#date_to String | The end date of the away mode in a %Y-%m-%d format. The date_to parameter is exclusive, which means the user will start receiving notifications on this date. |
first_name String | The user’s first name. |
comet_server String | The comet server. |
name String | The user’s full name. |
off_days List of integers | Sets the user’s off days (where they will get no notifications). It should be an array of integers representing ISO weekdays, e.g. 1 is Monday and 7 is Sunday. E.g. [6, 7] . |
restricted Boolean | Whether the user is restricted. |
default_workspace Integer | The user’s default workspace. |
token String | The user’s API token. |
snooze_dnd_end String | Stop time of do-not-disturb snooze for notifications. |
snoozed Boolean | Whether notifications are snoozed. |
email String | The user’s email. |
setup_pending Integer/Boolean | Whether setup is pending. |
snooze_until Integer | Snooze notifications for the specified number of seconds. |
Login
Example:
curl -X POST https://api.twist.com/api/v3/users/login \
-d email=user@example.com \
-d password=secret
POST /api/v3/users/login
Logs in existing user.
Parameters
Name | Required | Description |
---|---|---|
email String | Yes | The user’s email. |
password String | Yes | The user’s password. |
set_session_cookie Boolean | No | By default, a session cookie is set for the user. |
Return value
The user object.
Log out
Example:
curl -X POST https://api.twist.com/api/v3/users/logout
POST /api/v3/users/logout
Return value:
{
"status": "ok"
}
Logs out user, and resets the session.
Register
Example:
curl -X POST https://api.twist.com/api/v3/users/register \
-d name=User \
-d email=user@example.com \
-d password=secret
POST /api/v3/users/register
Register a new user.
Parameters
Name | Required | Description |
---|---|---|
name String | Yes | The user’s full name. |
email String | Yes | The user’s email. |
password String | Yes | The user’s password. |
Return value
The user object.
Update
Example:
curl -X POST https://api.twist.com/api/v3/users/update \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d name=User
POST /api/v3/users/update
Update the logged-in user’s details
Parameters
Name | Required | Description |
---|---|---|
name String | No | The user’s full name. |
email String | No | The user’s email. |
password String | No | The user’s password. |
default_workspace Integer | No | The user’s default workspace. |
profession String | No | The user’s profession. |
contact_info String | No | The user’s contact info. |
timezone String | No | The user’s timezone. |
snooze_until Integer | No | Snooze notifications for the specified number of seconds. |
snooze_dnd_start String | No | Start time of do-not-disturb snooze for notifications. |
snooze_dnd_end String | No | Stop time of do-not-disturb snooze for notifications. |
away_mode Object | No | Away mode sets the user as away until some future date. |
away_mode#type String | No | The reason of being in away mode may be parental , vacation , sickleave , or other . |
away_mode#date_from String | No | The start date of the away mode in a %Y-%m-%d format. The date_from parameter is inclusive. optional |
away_mode#date_to String | No | The end date of the away mode in a %Y-%m-%d format. The date_to parameter is exclusive, which means the user will start receiving notifications on this date. |
off_days List of integers | No | Sets the user’s off days (where they will get no notifications). It should be an array of integers representing ISO weekdays, e.g. 1 is Monday and 7 is Sunday. E.g. [6, 7] |
Return value
The updated user object is returned.
Update password
Example:
curl -X POST https://api.twist.com/api/v3/users/update_password \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d new_password=newsecret
POST /api/v3/users/update_password
Updates user’s password.
Parameters
Name | Required | Description |
---|---|---|
new_password String | Yes | The user’s new password. |
Return value
The user object is returned.
Update avatar
Example:
curl -X POST https://api.twist.com/api/v3/users/update_avatar \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-F image=@avatar.jpg
POST /api/v3/users/update_avatar
Updates user’s avatar. It currently supports the following formats:
- gif
- jpeg
- png
- bmp
- tiff
Note: the maximum allowed size for the avatar is 10MB
Parameters
Name | Required | Description |
---|---|---|
image String | Yes | Avatar image uploaded as multipart/form-data . |
Return value
The updated user object is returned.
Invalidate token
Example:
curl -X POST https://api.twist.com/api/v3/users/invalidate_token \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
POST /api/v3/users/invalidate_token
Invalidates API token and generates a new token for the user.
Return value
The user object is returned, which also includes the new token.
Validate token
Example:
curl -X POST https://api.twist.com/api/v3/users/validate_token \
-d token=9b1bf97783c1ad5593dee12f3019079dbd3042cf
POST /api/v3/users/validate_token
Return value:
{
"status": "ok"
}
Validates the user token.
Set presence
Example:
curl -X POST https://api.twist.com/api/v3/users/heartbeat \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d workspace_id=5517 \
-d platform=api
POST /api/v3/users/heartbeat
Return value:
{
"status": "ok"
}
Marks user as active on workspace.
Parameters
Name | Required | Description |
---|---|---|
workspace_id Integer | Yes | The id of the workspace. |
platform String | Yes | The platform can be one of mobile , desktop or api . |
Reset presence
Example:
curl -X POST https://api.twist.com/api/v3/users/reset_presence \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d workspace_id=5517
POST /api/v3/users/reset_presence
Return value:
{
"status": "ok"
}
Marks user as inactive on workspace.
Parameters
Name | Required | Description |
---|---|---|
workspace_id Integer | Yes | The id of the workspace. |
Reset password
Example:
curl -X POST https://api.twist.com/api/v3/users/reset_password \
-d email=user@example.com
POST /api/v3/users/reset_password
Return value:
{
"status": "ok"
}
Sends an email to reset the user’s password.
Parameters
Name | Required | Description |
---|---|---|
email String | Yes | The user’s email. |
Set password based on reset code
Example:
curl -X POST https://api.twist.com/api/v3/users/set_password \
-d reset_code=12345abcef
-d new_password=newsecret
POST /api/v3/users/set_password
Sets the user password based on a reset code.
Parameters
Name | Required | Description |
---|---|---|
reset_code String | Yes | The reset code sent via email. |
new_password String | Yes | The user’s new password. |
Return value
The updated user object is returned.
Check Google connection
Example:
curl https://api.twist.com/api/v3/users/is_connected_to_google \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
GET /api/v3/users/is_connected_to_google
Return value:
{
"google_connection": true,
"google_email": "amix4k@gmail.com"
}
Checks whether user’s account is connected to a Google account.
Disconnect from Google
Example:
curl -X POST https://api.twist.com/api/v3/users/disconnect_google \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
POST /api/v3/users/disconnect_google
Return value:
{
"status": "ok"
}
Disconnects user’s account from Google account.
Workspaces
A workspace is a shared place between different users. In the Twist UI they are usually called teams.
Workspace object:
{
"id": 5517,
"name": "Workspace1",
"color": 1,
"default_channel": 6984,
"default_conversation": 13030,
"creator": 10073,
"created_ts": 1494323073,
"plan": "unlimited"
}
Properties of workspace object
Name | Description |
---|---|
id Integer | The id of the workspace. |
name String | The name of the new workspace. |
color Integer | The color of the workspace. |
default_channel Integer | The id of the default channel. |
default_conversation Integer | The id of the default conversation. |
creator Integer | The id of the user that created the workspace. |
created_ts Integer | The Unix time when the workspace was created. |
plan String | The type of payment plan, either free or unlimited . |
Get workspace
Example:
curl --get https://api.twist.com/api/v3/workspaces/getone \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=5517
GET /api/v3/workspaces/getone
Gets a single workspace object by id.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the workspace. |
Return value
A workspace object is returned.
Get default workspace
Example:
curl https://api.twist.com/api/v3/workspaces/get_default \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf"
GET /api/v3/workspaces/get_default
Gets the user’s default workspace.
Return value
A workspace object is returned.
Get all workspaces
Example:
curl https://api.twist.com/api/v3/workspaces/get \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf"
GET /api/v3/workspaces/get
Gets all the user’s workspaces.
Return value
A list of workspace objects is returned.
Add workspace
Example:
curl -X POST https://api.twist.com/api/v3/workspaces/add \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d name=Workspace1
POST /api/v3/workspaces/add
Creates a new workspace.
Parameters
Name | Required | Description |
---|---|---|
name String | Yes | The name of the new workspace. |
temp_id Integer | No | The temporary id of the workspace. |
color Integer | No | The color of the workspace. |
Return value
A workspace object is returned.
Update workspace
Example:
curl -X POST https://api.twist.com/api/v3/workspaces/update \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=63109 \
-d name="New Name"
POST /api/v3/workspaces/update
Updates an existing workspace.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the workspace. |
name String | No | The name of the workspace. |
color Integer | No | The color of the workspace. |
Return value
The updated workspace object is returned.
Remove workspace
Example:
curl -X POST https://api.twist.com/api/v3/workspaces/remove \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=5517 \
-d current_password=secret
POST /api/v3/workspaces/remove
Return value:
{
"status": "ok"
}
Removes a workspace and all its data (not recoverable).
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the workspace. |
current_password String | Yes | The user’s current password. |
Get workspace users
GET /api/v3/workspaces/get_users
Returns a list of users for the given workspace id
Workspace user object:
curl -X POST https://api.twist.com/api/v3/workspaces/get_users \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=5517
Example response:
"user": {
"id": 10073,
"email": "user1@example.com",
"name": "User1",
"short_name": "User1",
"avatar_id": "c5f14f4da3ee2479a26c65c630c21765",
"default_workspace": null,
"profession": "",
"contact_info": "",
"timezone": "UTC",
"snooze_until": -1,
"snooze_dnd_start": null,
"snooze_dnd_end": null,
"away_mode": null,
"off_days": [],
"setup_pending": 0,
"is_bot": 0,
"user_type": "ADMIN",
"is_removed": 0,
"is_doist_employee": 0,
}
Properties of workspace user object
Name | Description |
---|---|
user_type String | The user type, one of ADMIN , USER or GUEST . |
is_removed Boolean | Whether the user has been removed. |
is_doist_employee Boolean | Whether the user is a Doist employee. |
Add user
Example:
curl -X POST https://api.twist.com/api/v3/workspaces/add_user \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=5517 \
-d email=user2@example.com
POST /api/v3/workspaces/add_user
Adds a person to a workspace.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the workspace. |
email String | Yes | The user’s email. |
name String | No | The user’s name. |
user_type String | No | The user type (‘USER’, ‘GUEST’, ‘ADMIN’) |
channel_ids List of Integers | No | A list of the channels ids. Ex: '[100, 101, 102]' |
Return value
A workspace user object is returned.
Resend invite
Example:
curl -X POST https://api.twist.com/api/v3/workspaces/resend_invite \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=5517 \
-d email=user2@example.com
POST /api/v3/workspaces/resend_invite
Return value:
{"status": "ok"}
Sends a new Workspace invitation to the selected user.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the workspace. |
email String | Yes | The user’s email. |
user_id Integer | No | The id of the user to invite. If available, it will be used instead of the user’s email. |
Update user
Example:
curl -X POST https://api.twist.com/api/v3/workspaces/update_user \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=5517 \
-d email=user2@example.com \
-d user_type=USER
POST /api/v3/workspaces/update_user
Updates a person in a workspace.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the workspace. |
user_type String | Yes | The user’s type one of USER , ADMIN or GUEST . |
email String | No | The email of the user to be updated. |
user_id Integer | No | The id of the user to update. If available, it will be used instead of the user’s email. |
Return value
The updated workspace user object is returned.
Remove user
Example:
curl -X POST https://api.twist.com/api/v3/workspaces/remove_user \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=5517 \
-d email=user2@example.com
POST /api/v3/workspaces/remove_user
Return value:
{
"status": "ok"
}
Removes a person from a workspace.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the workspace. |
email String | Yes | The user’s email. |
user_id Integer | No | The id of the user to remove. If available, it will be used instead of the user’s email. |
Get user by email
Example:
curl --get https://api.twist.com/api/v3/workspaces/get_user_by_email \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=5517 \
-d email=user2@example.com
GET /api/v3/workspaces/get_user_by_email
Gets user by email.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the workspace. |
email String | Yes | The user’s email. |
Return value
A workspace user object is returned.
Get user by id
Example:
curl --get https://api.twist.com/api/v3/workspaces/get_user_by_id \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=5517 \
-d user_id=10073
GET /api/v3/workspaces/get_user_by_id
Gets user by id.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the workspace. |
user_id Integer | Yes | The user’s id. |
Return value
A workspace user object is returned.
Get user info
Example:
curl --get https://api.twist.com/api/v3/workspaces/get_user_info \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=5517 \
-d user_id=10073
GET /api/v3/workspaces/get_user_info
Gets user’s info in the context of the workspace.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the workspace. |
user_id Integer | Yes | The user’s id. |
Get local time of user
Example:
curl --get https://api.twist.com/api/v3/workspaces/get_user_local_time \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=5517 \
-d user_id=10073
GET /api/v3/workspaces/get_user_local_time
Return value:
"2017-05-10 07:55:40"
Gets user’s local time.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the workspace. |
user_id Integer | Yes | The user’s id. |
Get public channels
Example:
curl --get https://api.twist.com/api/v3/workspaces/get_public_channels \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=5517
GET /api/v3/workspaces/get_public_channels
Gets public channels of workspace.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the workspace. |
Return value:
[
{
"workspace_id": 32345,
"user_ids": [
153454
],
"name": "Marketing",
"creator": 124657,
"color": 0,
"created_ts": 1518534447,
"description": "",
"archived": false,
"id": 10302,
"public": true
},
]
Groups
A group is a number of users grouped together under some name, a team.
Group object:
{
"id": 498,
"name": "Group1",
"description": null,
"user_ids": [],
"workspace_id": 5517,
}
Properties of group object
Name | Description |
---|---|
id Integer | The id of the group. |
name String | The name of the group. |
description String | The description of the group. |
user_ids List of Integers | The users that are part of the group. |
workspace_id Integer | The id of the workspace. |
Get group
Example:
curl --get https://api.twist.com/api/v3/groups/getone \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=498
GET /api/v3/groups/getone
Gets a single group object.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the group. |
Return value
A group object is returned.
Get all groups
Example:
curl --get https://api.twist.com/api/v3/groups/get \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d workspace_id=5517
GET /api/v3/groups/get
Gets all groups in a workspace.
Parameters
Name | Required | Description |
---|---|---|
workspace_id Integer | Yes | The id of the workspace. |
Return value
A list of group objects is returned.
Add group
Example:
curl -X POST https://api.twist.com/api/v3/groups/add \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d workspace_id=5571 \
-d name=Group1 \
-d user_ids='[10073]'
POST /api/v3/groups/add
Adds a new group to a workspace.
Parameters
Name | Required | Description |
---|---|---|
workspace_id Integer | Yes | The id of the workspace. |
name String | Yes | The name of the new group. |
user_ids List of Integers | No | The users that will comprise the group. |
Return value
A group object is returned.
Update group
Example:
curl -X POST https://api.twist.com/api/v3/groups/update \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=498 \
-d name=Group1
POST /api/v3/groups/update
Updates an existing group.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the group. |
name String | Yes | The name of the group. |
Return value
The updated group object is returned.
Remove group
Example:
curl -X POST https://api.twist.com/api/v3/groups/remove \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=498
POST /api/v3/groups/remove
Return value:
{
"status": "ok"
}
Removes a group.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the group. |
Add user
Example:
curl -X POST https://api.twist.com/api/v3/groups/add_user \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=498 \
-d user_id=10076
POST /api/v3/groups/add_user
Return value:
{
"status": "ok"
}
Adds a person to a group.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the group. |
user_id Integer | Yes | The user’s id. |
Add users
Example:
curl -X POST https://api.twist.com/api/v3/groups/add_users \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=498 \
-d user_ids='[10073,10076]'
POST /api/v3/groups/add_users
Return value:
{
"status": "ok"
}
Adds several persons to a group.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the group. |
user_ids List of Integers | Yes | The ids of the users. |
Remove user
Example:
curl -X POST https://api.twist.com/api/v3/groups/remove_user \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=498 \
-d user_id=10076
POST /api/v3/groups/remove_user
Return value:
{
"status": "ok"
}
Removes a person from a group.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the group. |
user_id Integer | Yes | The user’s id. |
Remove users
Example:
curl -X POST https://api.twist.com/api/v3/groups/remove_users \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=498 \
-d user_ids='[10073,10076]'
POST /api/v3/groups/remove_users
Return value:
{
"status": "ok"
}
Removes several persons from a group.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the group. |
user_ids List of Integers | Yes | The ids of the users. |
Channels
A channel is a topic of discussion between a number of users.
Channel object:
{
"id": 6984,
"name": "Channel1",
"description": "",
"creator": 10073,
"user_ids": [
2601,
10073,
10076
],
"color": 1,
"public": true,
"workspace_id": 5517,
"archived": false,
"created_ts": 1494323074,
}
Properties of channel object
Name | Description |
---|---|
id Integer | The id of the channel. |
name String | The name of the channel. |
description String | The description of the channel. |
creator Integer | The user that created the channel. |
user_ids List of Integers | The users that will participate in the channel. |
color Integer | The color of the channel. |
public Boolean | If enabled, the channel will be marked as public. |
workspace_id Integer | The id of the workspace. |
archived Boolean | Whether the channel is archived. |
created_ts Integer | The Unix time when the channel was created. |
Get channel
Example:
curl --get https://api.twist.com/api/v3/channels/getone \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=6984
GET /api/v3/channels/getone
Gets a single channel object by id.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the channel. |
Return value
A channel object is returned.
Get all channels
Example:
curl --get https://api.twist.com/api/v3/channels/get \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d workspace_id=5517
GET /api/v3/channels/get
Gets all channels in a workspace.
Parameters
Name | Required | Description |
---|---|---|
workspace_id Integer | Yes | The id of the workspace. |
archived Boolean | No | If enabled, only archived conversations are returned. By default this is disabled. |
Return value
A list of channel objects is returned.
Add channel
Example:
curl -X POST https://api.twist.com/api/v3/channels/add \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d workspace_id=5517 \
-d name=Channel1
POST /api/v3/channels/add
Adds a new channel.
Parameters
Name | Required | Description |
---|---|---|
workspace_id Integer | Yes | The id of the workspace. |
name String | Yes | The name of the new channel. |
temp_id Integer | No | The temporary id of the channel. |
user_ids List of Integers | No | The users that will participate in the channel. |
color Integer | No | The color of the channel. |
public Boolean | No | If enabled, the channel will be marked as public. Defaults to false . |
description String | No | The description of the channel. |
Return value
A channel object is returned.
Update channel
Example:
curl -X POST https://api.twist.com/api/v3/channels/update \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=6984 \
-d name=Channel1
POST /api/v3/channels/update
Updates an existing channel.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the channel. |
name String | Yes | The name of the new channel. |
color Integer | No | The color of the channel. |
public Boolean | No | If enabled, the channel will be marked as public. |
description String | No | The description of the channel. |
Return value
The updated channel object is returned.
Archive channel
Example:
curl -X POST https://api.twist.com/api/v3/channels/archive \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=6984
POST /api/v3/channels/archive
Return value:
{
"status": "ok"
}
Archives a channel.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the channel. |
Unarchive channel
Example:
curl -X POST https://api.twist.com/api/v3/channels/unarchive \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=6984
POST /api/v3/channels/unarchive
Return value:
{
"status": "ok"
}
Unarchives a channel.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the channel. |
Remove channel
Example:
curl -X POST https://api.twist.com/api/v3/channels/remove \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=6984
POST /api/v3/channels/remove
Removes a channel. Requires for the channel to be archived first.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the channel. |
Return value
{
"status": "ok"
}
Add user
Example:
curl -X POST https://api.twist.com/api/v3/channels/add_user \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=6984 \
-d user_id=10076
POST /api/v3/channels/add_user
Return value:
{
"status": "ok"
}
Adds a person to a channel.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the channel. |
user_id Integer | Yes | The user’s id. |
Add users
Example:
curl -X POST https://api.twist.com/api/v3/channels/add_users \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=6984 \
-d user_ids='[10076]'
POST /api/v3/channels/add_users
Return value:
{
"status": "ok"
}
Adds several persons to a channel.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the channel. |
user_ids List of Integers | Yes | The ids of the users. |
Remove user
Example:
curl -X POST https://api.twist.com/api/v3/channels/remove_user \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=6984 \
-d user_id=10076
POST /api/v3/channels/remove_user
Return value:
{
"status": "ok"
}
Removes a person from a channel.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the channel. |
user_id Integer | Yes | The user’s id. |
Remove users
Example:
curl -X POST https://api.twist.com/api/v3/channels/remove_users \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=6984 \
-d user_ids='[10076]'
POST /api/v3/channels/remove_users
Return value:
{
"status": "ok"
}
Removes several persons from a channel.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the channel. |
user_ids List of Integers | Yes | The ids of the users. |
Threads
A thread is a discussion separated by topic.
Thread object:
{
"id": 32038,
"title": "Thread1",
"content": "Let's discuss the Twist API...",
"starred": 0,
"creator": 10073,
"channel_id": 6984,
"workspace_id": 5517,
"attachments": [],
"actions": [],
"recipients": [
10076
],
"participants": [
10073,
10076
],
"groups": [],
"reactions": {},
"comment_count": 3,
"last_obj_index": 2,
"snippet": "OK!",
"snippet_creator": 10073,
"last_updated_ts": 1494500713,
"muted_until": null,
"system_message": null,
"posted_ts": 1494488709,
"last_edited_ts": 1494488709,
}
Properties of thread object
Name | Description |
---|---|
id Integer | The id of the thread. |
title String | The title of the thread. |
content String | The content of the thread. |
starred Integer | Whether the thread is starred. |
creator Integer | The user that created the thread. |
channel_id Integer | The id of the channel. |
workspace_id Integer | The id of the workspace. |
attachments List of Attachments | Files attached to the comment. |
actions List of Action buttons | Action buttons attached to the comment. |
recipients List of Integers or String | The users that were initially attached to the the thread, or EVERYONE . |
participants List of Integers | The users that were at some point attached to the thread or one of its comments. |
groups List of Integers | The groups that will be notified. |
reactions Object | Reactions to the thread, where keys are the reactions and values the users that had that reaction. |
comment_count Integer | The number of comments. |
last_obj_index Integer | The last comment’s index. |
snippet String | A part of the last comment. |
snippet_creator Integer | The user id of the last comment. |
last_updated_ts Integer | The Unix time when the thread was last updated. |
muted_until Integer | The Unix time until when the thread is muted. |
system_message String | A system message. |
posted_ts Integer | The Unix time when the thread was created. |
last_edited_ts Integer | The Unix time when the thread was last edited or null if it hasn’t. |
Get thread
Example:
curl --get https://api.twist.com/api/v3/threads/getone \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=32038
GET /api/v3/threads/getone
Gets a thread object by id.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the thread. |
Return value
A thread object is returned.
Get all threads
Example:
curl --get https://api.twist.com/api/v3/threads/get \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d channel_id=6984
GET /api/v3/threads/get
Gets all threads in a channel.
Parameters
Name | Required | Description |
---|---|---|
channel_id Integer | Yes | The id of the channel. |
workspace_id Integer | No | The id of the workspace. |
filter_by String | No | A filter can be one of attached_to_me , everyone and is_starred . |
newer_than_ts Integer | No | Limits threads to those newer when the specified Unix time. |
older_than_ts Integer | No | Limits threads to those older when the specified Unix time. |
limit Integer | No | Limits the number of threads returned. |
as_ids Boolean | No | If enabled, only the ids of the threads are returned. |
Return value
A list of thread objects is returned.
Add thread
Example:
curl -X POST https://api.twist.com/api/v3/threads/add \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d channel_id=6984 \
-d title=Thread1
# Create a thread with an attachment using two requests
curl -X POST https://api.twist.com/api/v3/threads/add \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d channel_id=6984 \
-d title=Thread1
-d attachments=[$(curl -X POST https://api.twist.com/api/v3/attachments/upload -F attachment_id=$(uuidgen) -F file_name=@mytext.txt -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf")]
POST /api/v3/threads/add
Adds a new thread to a channel.
Parameters
Name | Required | Description |
---|---|---|
channel_id Integer | Yes | The id of the channel. |
title String | Yes | The title of the new thread. |
content String | Yes | The content of the new thread. |
attachments List of Attachments | No | List of attachments to the new thread. It must follow the JSON format returned by attachment#upload. |
actions List of Action Buttons | No | List of action to the new thread. More information about the format of the object available at the add an action button submenu. |
recipients List of Integers or String | No | The users that will be attached to the thread, or EVERYONE . |
groups List of Integers | No | The groups that will be notified. |
temp_id Integer | No | The temporary id of the thread. |
send_as_integration Boolean | No | Displays the integration as the thread creator. |
Return value
A thread object is returned.
Update thread
Example:
curl -X POST https://api.twist.com/api/v3/threads/update \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=32038 \
-d title=Thread1
# Update a thread with an attachment using two requests
curl -X POST https://api.twist.com/api/v3/threads/add \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d channel_id=6984 \
-d title=Thread1 \
-d attachments=[$(curl -X POST https://api.twist.com/api/v3/attachments/upload -F attachment_id=$(uuidgen) -F file_name=@mytext.txt -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf")]
POST /api/v3/threads/update
Updates an existing thread.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the thread. |
title String | No | The title of the thread. |
content String | No | The content of the thread. |
attachments List of Attachments | No | List of attachments to the thread. It must follow the JSON format returned by attachment#upload. |
actions List of Action Buttons | No | List of action to the thread. More information about the format of the object available at the add an action button submenu. |
Return value
The updated thread object is returned.
Remove thread
Example:
curl -X POST https://api.twist.com/api/v3/threads/remove \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=32038
POST /api/v3/threads/remove
Removes a thread.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the thread. |
Return value
{
"status": "ok"
}
Star thread
Example:
curl -X POST https://api.twist.com/api/v3/threads/star \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=32038
POST /api/v3/threads/star
Stars a thread.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the thread. |
Return value:
{
"status": "ok"
}
Unstar thread
Example:
curl -X POST https://api.twist.com/api/v3/threads/unstar \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=32038
POST /api/v3/threads/unstar
Unstars a thread.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the thread. |
Return value:
{
"status": "ok"
}
Move thread
Example:
curl -X POST https://api.twist.com/api/v3/threads/move_to_channel \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=6984 \
-d to_channel=6984
POST /api/v3/threads/move_to_channel
Moves thread to a different channel.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the thread. |
to_channel Integer | Yes | The target channel’s id. |
Return value:
{
"status": "ok"
}
Follow thread
Example:
curl -X POST https://api.twist.com/api/v3/threads/follow \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=32038
POST /api/v3/threads/follow
Follows thread.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the thread. |
Return value:
{
"status": "ok"
}
Unfollow thread
Example:
curl -X POST https://api.twist.com/api/v3/threads/unfollow \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=32038
POST /api/v3/threads/unfollow
Unfollows thread.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the thread. |
Return value:
{
"status": "ok"
}
Get unread threads
Example:
curl --get https://api.twist.com/api/v3/threads/get_unread \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d workspace_id=5517
GET /api/v3/threads/get_unread
Gets unread threads in a workspace.
Parameters
Name | Required | Description |
---|---|---|
workspace_id Integer | Yes | The id of the workspace. |
Return value:
[
[
85302, // channel_id
439203, // thread_id
-1 // last_read_object_index
]
]
Return value
A list of unread thread objects, where each unread thread object is an array with three values: the channel id, the thread id and the index of the last unread comment.
Mark thread as read
Example:
curl -X POST https://api.twist.com/api/v3/threads/mark_read \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d thread_id=32038 \
-d obj_index=2
POST /api/v3/threads/mark_read
Marks thread as read.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the thread. |
obj_index Integer | Yes | The index of the last known read message. |
Return value:
{
"status": "ok"
}
Mark thread as unread
Example:
curl -X POST https://api.twist.com/api/v3/threads/mark_unread \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=32038 \
-d obj_index=2
POST /api/v3/threads/mark_unread
Marks thread as unread.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the thread. |
obj_index Integer | Yes | The index of the last unread message. |
Return value:
{
"status": "ok"
}
Mark all threads as read
Example:
curl -X POST https://api.twist.com/api/v3/threads/mark_all_read \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d channel_id=6984
POST /api/v3/threads/mark_all_read
Marks all thread in workspace or channel as read.
Parameters
Name | Required | Description |
---|---|---|
workspace_id Integer | Yes, this or channel_id . |
The id of the workspace. |
channel_id Integer | Yes, this or workspace_id . |
The id of the channel. |
Return value:
{
"status": "ok"
}
Clear unread threads
Example:
curl -X POST https://api.twist.com/api/v3/threads/clear_unread \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d workspace_id=5517
POST /api/v3/threads/clear_unread
Clears unread threads in workspace.
Parameters
Name | Required | Description |
---|---|---|
workspace_id Integer | Yes | The id of the workspace. |
Return value:
{
"status": "ok"
}
Mute thread
Example:
curl -X POST https://api.twist.com/api/v3/threads/mute \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=13037 \
-d minutes=30
POST /api/v3/threads/mute
Mutes a thread for a number of minutes.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the thread. |
minutes Integer | Yes | The number of minutes to mute the thread. |
Return value
A thread object is returned.
Unmute thread
Example:
curl -X POST https://api.twist.com/api/v3/threads/unmute \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=13037
POST /api/v3/threads/unmute
Unmutes a thread.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the thread. |
Return value
A thread object is returned.
Comments
A comment is a message in a thread.
Comment object:
{
"id": 206113,
"content": "OK!",
"creator": 10076,
"thread_id": 32038,
"channel_id": 6984,
"workspace_id": 5517,
"obj_index": 2,
"attachments": [],
"recipients": [
10073
],
"groups": [],
"reactions": {
"π": [
10076
]
},
"is_deleted": false,
"system_message": null,
"posted_ts": 1494489787,
"last_edited_ts": 1494488709,
}
Properties of comment object
Name | Description |
---|---|
id Integer | The id of the comment. |
content String | The content of the new comment. |
creator Integer | The user that added the comment. |
thread_id Integer | The id of the thread. |
channel_id Integer | The id of the channel. |
workspace_id Integer | The id of the workspace. |
attachments List of Attachments | Files attached to the comment. |
actions List of Action buttons | Action buttons attached to the comment. |
recipients List of Integers or String | The users that will be notified, or EVERYONE or EVERYONE_IN_THREAD . |
groups List of Integers | The groups that will be notified. |
reactions Object | Reactions to the thread, where keys are the reactions and values the users that had that reaction. |
is_deleted Integer | Whether the thread is deleted. |
system_message String | A system message. |
posted_ts Integer | The Unix time when the thread was created. |
last_edited_ts Integer | The Unix time when the comment was last edited or null if it hasn’t. |
Get comment
Example:
curl --get https://api.twist.com/api/v3/comments/getone \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=206113
GET /api/v3/comments/getone
Gets a single comment object by id.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the comment. |
Return value
A comment object is returned.
Get all comments
Example:
curl --get https://api.twist.com/api/v3/comments/get \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d thread_id=32038
GET /api/v3/comments/get
Gets all comments in a thread.
Parameters
Name | Required | Description |
---|---|---|
thread_id Integer | Yes | The id of the thread. |
newer_than_ts String | No | Limit comments to those newer than the specified Unix timestamp. |
older_than_ts String | No | Limit comments to those older than the specified Unix timestamp. |
from_obj_index Integer | No | Limit comments starting at the specified object index. |
to_obj_index String | No | Limit comments ending at the specified object index. |
limit Integer | No | Limits the number of comments returned, by default 20 . |
order_by String | No | The order of the comments returned one of DESC or ASC . |
as_ids Boolean | No | If enabled, only the ids of the comments are returned. |
Return value
A list of comment objects is returned.
Add comment
Example:
curl -X POST https://api.twist.com/api/v3/comments/add \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d thread_id=32038 \
-d content="OK!"
# Create a comment with an attachment using two requests
curl -X POST https://api.twist.com/api/v3/comments/add \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d thread_id=32038 \
-d content="OK!" \
-d attachments=[$(curl -X POST https://api.twist.com/api/v3/attachments/upload -F attachment_id=$(uuidgen) -F file_name=@mytext.txt -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf")]
POST /api/v3/comments/add
Adds a new comment to a thread.
Parameters
Name | Required | Description |
---|---|---|
thread_id Integer | Yes | The id of the thread. |
content String | Yes | The content of the new comment. |
attachments List of Attachments | No | List of attachments to the new comment. It must follow the JSON format returned by attachment#upload. |
actions List of Action Buttons | No | List of action to the new comment. More information about the format of the object available at the add an action button submenu. |
recipients List of Integers or String | No | The users that will be notified, or EVERYONE or EVERYONE_IN_THREAD . If not provided, EVERYONE_IN_THREAD will be used. |
groups List of Integers | No | The groups that will be notified. |
temp_id Integer | No | The temporary id of the comment. |
mark_thread_position Boolean | No | By default, the position of the thread is marked. |
send_as_integration Boolean | No | Displays the integration as the comment creator. |
Return value
A comment object is returned.
Update comment
Example:
curl -X POST https://api.twist.com/api/v3/comments/update \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=206113 \
-d content="OK!"
# Update a comment with an attachment using two requests
curl -X POST https://api.twist.com/api/v3/comments/update \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=206113 \
-d content="OK!" \
-d attachments=[$(curl -X POST https://api.twist.com/api/v3/attachments/upload -F attachment_id=$(uuidgen) -F file_name=@mytext.txt -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf"])
POST /api/v3/comments/update
Updates an existing comment.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the comment. |
content String | No | The content of the comment. |
attachments List of Attachments | No | List of attachments to the new comment. It must follow the JSON format returned by attachment#upload. |
actions List of Action Buttons | No | List of action to the new comment. More information about the format of the object available at the add an action button submenu. |
Return value
A comment object is returned.
Remove comment
Example:
curl -X POST https://api.twist.com/api/v3/comments/remove \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=206113
POST /api/v3/comments/remove
Removes a comment (only user’s own comments can be removed).
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the comment. |
Return value:
{
"status": "ok"
}
Mark position
Example:
curl -X POST https://api.twist.com/api/v3/comments/mark_position \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d thread_id=32038 \
-d comment_id=206113
POST /api/v3/comments/mark_position
Marks the position of a thread.
Parameters
Name | Required | Description |
---|---|---|
thread_id Integer | Yes | The id of the thread. |
comment_id Integer | Yes | The id of the comment. |
Return value:
{
"status": "ok"
}
Conversations
A conversation is a direct message exchange between one or more users.
Conversation object:
{
"id": 13037,
"title": null,
"private": 1,
"creator": 10076,
"last_message": {
"reactions": {},
"workspace_id": 1245,
"creator": 133822,
"deleted": false,
"actions": [],
"conversation_id": 321441,
"last_edited_ts": null,
"direct_mentions": [],
"system_message": null,
"id": 6234671,
"attachments": [],
"posted_ts": 1533478422,
"obj_index": 7,
"content": "Hello World!"
},
"workspace_id": 5517,
"user_ids": [
10073,
10076
],
"message_count": 2,
"last_obj_index": 1,
"snippet": "Hello!",
"snippet_creators": [
10076,
10073
],
"last_active_ts": 1497970961,
"muted_until": null,
"archived": 0,
"created_ts": 1494330846,
}
Properties of conversation object
Name | Description |
---|---|
id Integer | The id of the conversation. |
title String | The title of the conversation, or null if a private conversation. |
private Integer | Whether the conversation is private, ie. between 2 users only. |
creator Integer | The user that created the thread. |
last_message Object | An object containing information about the last message. |
workspace_id Integer | The id of the workspace. |
user_ids List of Integers | The users that are participating in the conversation. |
last_obj_index Integer | The last message’s index. |
snippet String | A part of the last comment. |
snippet_creators List of Integers | The users of the last comments. |
last_active_ts Integer | The Unix time when the conversation was last active. |
muted_until Integer | The Unix time until when the conversation is muted. |
archived Integer | Whether the conversation is archived. |
created_ts Integer | The Unix time when the conversation was created. |
Get conversation
Example:
curl --get https://api.twist.com/api/v3/conversations/getone \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=13037
GET /api/v3/conversations/getone
Gets a single conversation object.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the conversation. |
Return value
A conversation object is returned.
Get or create conversation
Example:
curl -X POST https://api.twist.com/api/v3/conversations/get_or_create \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d workspace_id=5517 \
-d user_ids='[10073,10076]'
POST /api/v3/conversations/get_or_create
Gets or creates a conversation with one or more users.
Parameters
Name | Required | Description |
---|---|---|
workspace_id Integer | Yes | The id of the workspace. |
user_ids List of Integers | Yes | The users that will participate in the conversation. |
Return value
A conversation object is returned.
Get all conversations
Example:
curl --get https://api.twist.com/api/v3/conversations/get \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d workspace_id=5517
GET /api/v3/conversations/get
Gets all conversations of a user in a workspace.
Parameters
Name | Required | Description |
---|---|---|
workspace_id Integer | Yes | The id of the workspace. |
limit Integer | No | Limits the number of conversations. |
newer_than_ts Integer | No | Limits conversations to those newer when the specified Unix time. |
older_than_ts Integer | No | Limits conversations to those older when the specified Unix time. |
order_by String | No | The order of the comments returned one of DESC or ASC . |
archived Boolean | No | If enabled, only archived conversations are returned. By default it’s disabled. |
Return value
A list of conversation objects is returned.
Update conversation
Example:
curl -X POST https://api.twist.com/api/v3/conversations/update \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=13037 \
-d title=Title1
POST /api/v3/conversations/update
Updates an existing conversation.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the conversation. |
title String | Yes | The title of the conversation. |
archived Boolean | No | If enabled, the conversation is marked as archived. |
Return value
A conversation object is returned.
Add user
Example:
curl -X POST https://api.twist.com/api/v3/conversations/add_user \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=13037 \
-d user_id=10076
POST /api/v3/conversations/add_user
Adds a person to a conversation.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the conversation. |
user_id Integer | Yes | The user’s id. |
Return value:
{
"status": "ok"
}
Add users
Example:
curl -X POST https://api.twist.com/api/v3/conversations/add_users \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=13037 \
-d user_ids='[10076]'
POST /api/v3/conversations/add_users
Adds several persons to a conversation.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the conversation. |
user_ids List of Integers | Yes | The ids of the users. |
Return value:
{
"status": "ok"
}
Remove user
Example:
curl --get https://api.twist.com/api/v3/conversations/remove_user \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=13037 \
-d user_id=10076
GET /api/v3/conversations/remove_user
Removes a person from a conversation.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the conversation. |
user_id Integer | Yes | The user’s id. |
Return value:
{
"status": "ok"
}
Remove users
Example:
curl --get https://api.twist.com/api/v3/conversations/remove_users \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=13037 \
-d user_ids='[10076]'
GET /api/v3/conversations/remove_users
Removes several persons from a conversation.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the conversation. |
user_ids List of Integers | Yes | The ids of the users. |
Return value:
{
"status": "ok"
}
Archive conversation
Example:
curl -X POST https://api.twist.com/api/v3/conversations/archive \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=13037
POST /api/v3/conversations/archive
Archives a conversation.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the conversation. |
Return value:
{
"status": "ok"
}
Unarchive conversation
Example:
curl -X POST https://api.twist.com/api/v3/conversations/unarchive \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=13037
POST /api/v3/conversations/unarchive
Unarchives a conversation.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the conversation. |
Return value:
{
"status": "ok"
}
Get unread conversations
Example:
curl --get https://api.twist.com/api/v3/conversations/get_unread \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=5517
GET /api/v3/conversations/get_unread
Gets unread conversations.
Parameters
Name | Required | Description |
---|---|---|
workspace_id Integer | Yes | The id of the workspace. |
Return value:
[
[
13037,
1
]
]
Return value
A list of unread conversation objects, where each unread conversation object is an array with two values: the conversation id and the index of the last unread message.
Mark conversation as read
Example:
curl -X POST https://api.twist.com/api/v3/conversations/mark_read \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d conversation_id=13037 \
-d messsage_id=1
POST /api/v3/conversations/mark_read
Marks a conversation as read.
Parameters
Name | Required | Description |
---|---|---|
conversation_id Integer | Yes | The id of the conversation. |
obj_index Integer | Yes, this or message_id |
The index of the message, which will become the last read message in the conversation. |
message_id Integer | Yes, this or obj_index |
The id of the message, which will become the last read message in the conversation. |
Return value:
{
"status": "ok"
}
Mark conversation as unread
Example:
curl -X POST https://api.twist.com/api/v3/conversations/mark_unread \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d conversation_id=13037 \
-d messsage_id=1
POST /api/v3/conversations/mark_unread
Marks a conversation as unread.
Parameters
Name | Required | Description |
---|---|---|
conversation_id Integer | Yes | The id of the conversation. |
obj_index Integer | Yes, this or message_id |
The index of the message, which will become the last unread message in the conversation. |
message_id Integer | Yes, this or obj_index |
The id of the message, which will become the last unread message in the conversation. |
Return value:
{
"status": "ok"
}
Mute conversation
Example:
curl -X POST https://api.twist.com/api/v3/conversations/mute \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=13037 \
-d minutes=30
POST /api/v3/conversations/mute
Mutes a conversation for a number of minutes.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the conversation. |
minutes Integer | Yes | The number of minutes to mute the conversation. |
Return value
A conversation object is returned.
Unmute conversation
Example:
curl -X POST https://api.twist.com/api/v3/conversations/unmute \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=13037
POST /api/v3/conversations/unmute
Unmutes a conversation.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the conversation. |
Return value
A conversation object is returned.
Conversation messages
A conversation message is a message between one or more users participating in a conversation.
Conversation message object:
{
"id": 514069,
"content": "Hi!",
"creator": 10073,
"conversation_id": 13037,
"workspace_id": 5517,
"obj_index": 0,
"attachments": [],
"actions": [],
"reactions": {},
"is_deleted": false,
"system_message": null,
"posted_ts": 1497970956,
"last_edited_ts": 1494488709,
},
Properties of conversation message object
Name | Description |
---|---|
id Integer | The id of the message. |
content String | The content of the message. |
creator Integer | The user that added the message. |
conversation_id Integer | The id of the conversation. |
workspace_id Integer | The id of the workspace. |
obj_index Integer | The index of the message in regards to all other messages in the conversation. |
attachments List of Attachments | Files attached to the comment. |
actions List of Action buttons | Action buttons attached to the comment. |
reactions Object | Reactions to the thread, where keys are the reactions and values the users that had that reaction. |
is_deleted Integer | Whether the message is deleted. |
system_message String | A system message. |
posted_ts Integer | The Unix time when the message was created. |
last_edited_ts Integer | The Unix time when the message was last edited or null if it hasn’t. |
Get message
Example:
curl --get https://api.twist.com/api/v3/conversation_messages/getone \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=514069
GET /api/v3/conversation_messages/getone
Gets a single conversation message.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the conversation message. |
Return value
A conversation message object is returned.
Get all messages
Example:
curl --get https://api.twist.com/api/v3/conversation_messages/get \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d conversation_id=13037
GET /api/v3/conversation_messages/get
Gets messages from a conversation.
Parameters
Name | Required | Description |
---|---|---|
conversation_id Integer | Yes | The id of the conversation. |
limit Integer | No | Limits the number of messages returned. |
from_obj_index Integer | No | Limit messages starting at the specified object index. |
to_obj_index String | No | Limit messages ending at the specified object index. |
order_by String | No | The order of the conversations returned one of DESC or ASC . |
as_ids Boolean | No | If enabled, only the ids of the messages are returned. |
Return value
A list of conversation message objects is returned.
Add message to conversation
Example:
curl -X POST https://api.twist.com/api/v3/conversation_messages/add \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d conversation_id=13037 \
-d content="Hello!"
# Create a message with an attachment using two requests
curl -X POST https://api.twist.com/api/v3/conversation_messages/add \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d conversation_id=13037 \
-d content="Hello!" \
-d attachments=[$(curl -X POST https://api.twist.com/api/v3/attachments/upload -F attachment_id=$(uuidgen) -F file_name=@mytext.txt -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf")]
POST /api/v3/conversation_messages/add
Adds a message to an existing conversation.
Parameters
Name | Required | Description |
---|---|---|
conversation_id Integer | Yes | The id of the conversation. |
content String | Yes | The content of the new message. |
attachments List of Attachments | No | List of attachments to the message. It must follow the JSON format returned by attachment#upload. |
actions List of Action Buttons | No | List of action to the new message. More information about the format of the object available at the add an action button submenu. |
Return value
A conversation message object is returned.
Update message in conversation
Example:
curl -X POST https://api.twist.com/api/v3/conversation_messages/update \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d conversation_id=13037 \
-d content="Hello!"
# Update a message with an attachment using two requests
curl -X POST https://api.twist.com/api/v3/conversation_messages/update \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=130371 \
-d content="Hello!" \
-d attachments=[$(curl -X POST https://api.twist.com/api/v3/attachments/upload -F attachment_id=$(uuidgen) -F file_name=@mytext.txt -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf")]
POST /api/v3/conversation_messages/update
Updates a message in conversation.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the message. |
content String | No | The content of the new message. |
attachments List of Attachments | No | List of attachments to the message. It must follow the JSON format returned by attachment#upload. |
actions List of Action Buttons | No | List of action to the message. More information about the format of the object available at the add an action button submenu. |
Return value
A conversation message object is returned.
Remove message from conversation
Example:
curl -X POST https://api.twist.com/api/v3/conversation_messages/remove \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d id=514069
POST /api/v3/conversation_messages/remove
Removes a message from conversation.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the message. |
Return value:
{
"status": "ok"
}
Action buttons
Action buttons are used inside other objects
like threads, comments
or messages. As it’s possible to have many
action buttons inside the same object, they are represented as a list
of action buttons in the actions
key.
They are used to make it easy to execute an action for the message received. An example of usage would be adding text to the message box or a link to another page.
Action buttons objects:
{
...,
"actions": [
{
"action": "open_url",
"url": "https://www.google.com",
"type": "action",
"button_text": "Open Url Action Btn"
},
{
"action": "prefill_message",
"message": "This message is prefilled by an action button",
"type": "action",
"button_text": "Prefill Message Action Btn"
},
{
"action": "send_reply",
"message": "This reply was sent by an action button",
"type": "action",
"button_text": "Send Reply Action Btn"
},
],
...
}
Properties of the action button object
Name | Description |
---|---|
action String | The action of the button. It can be open_url, prefill_message, or send_reply. |
type String | The type of the button, for now just action is available. |
button_text String | The text for the action button. |
message String | Message to be added when using prefill_* and send_*actions. |
url String | URL to redirect. It’s used for open_url types. |
Get action buttons
Action buttons cannot be retrieved alone, they are part of other objects like threads, comments, and messages. To retrieve them, use the get methods from the object in which they were inserted.
Add an action button
Action buttons cannot be added alone, they are part of other objects like threads, comments, and messages. To add them, you have to use the add methods from the object in which they will be inserted into.
Parameters to add new action buttons
Name | Required | Description |
---|---|---|
action String | Yes | The action of the button. It can be open_url, prefill_message, or send_reply. |
type String | Yes | The type of the button, for now just action is available. |
button_text String | Yes | The text for the action button. |
message String | No | Message to be added when using prefill_* and send_* actions. |
url String | No | URL to redirect in case the action used requires it. |
Attachments
Files can be attached to threads, comments, or conversation messages.
Note: The maximum allowed size for the attachment is 100MB
Example:
{
"attachment_id": "c8f962d3-491b-4a43-92c2-43f7ac076408",
"title": "image.png",
"url": "https://xxx.cloudfront.net/xxx/as/image.png",
"url_type": "image",
"file_name": "image.png",
"file_size": 21601,
"underlying_type": "image/png",
"image": "https://xxx.cloudfront.net/xxx/as/image.png",
"image_height": 100,
"image_width": 100,
"upload_state": "uploaded"
}
Properties
Name | Description |
---|---|
attachment_id String | The id of the attachment. |
title String | The title of the attachment. |
url String | The URL where the file is located. |
file_name String | The file’s name. |
file_size Integer | The file’s size in bytes. |
underlying_type String | The file’s media or content type (MIME). |
upload_state String | Upload state is uploaded on success, or failed otherwise. |
url_type String | The type of the file, such as file or image . |
image String | If file is an image , the URL to the image file. |
image_width Integer | If file is an image , the width of the image. |
image_height Integer | If file is an image , the height of the image. |
duration String | If file is audio , the duration of the audio. |
Upload an attachment
Example:
curl -X POST https://api.twist.com/api/v3/attachments/upload \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-F attachment_id=c8f962d3-491b-4a43-92c2-43f7ac076408 \
-F file_name=@image.png
POST /api/v3/attachments/upload
Uploads a file.
Parameters
Name | Required | Description |
---|---|---|
attachment_id String | Yes | A UUID that will be the id of the attachment. |
file_name String | Yes | The name of the file to be uploaded. |
Return value
An attachment object is returned.
Remove an attachment
Example:
curl -X POST https://api.twist.com/api/v3/attachments/upload \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d attachment_id=c8f962d3-491b-4a43-92c2-43f7ac076408 \
-d comment_id=241432
POST /api/v3/attachments/remove
Removes attachment from thread, comment or conversation message.
Parameters
Name | Required | Description |
---|---|---|
attachment_id Integer | Yes | The id of the attachment. |
thread_id Integer | Yes, this or comment_id or message_id |
The id of the thread. |
comment_id Integer | Yes, this or thread_id or message_id |
The id of the comment. |
message_id Integer | Yes, this or thread_id or comment_id |
The id of the conversation message. |
Return value:
{
"status": "ok"
}
Reactions
Reactions can be added to threads, comments or conversation messages.
Reaction object:
{
"π": [
10076,
10073
],
"π": [
10076
]
}
Properties of reaction object
The reaction object is either null
or has one or more key-value pairs.
Name | Description |
---|---|
key String | The reaction added by one or more users. |
value List of Integers | The users that added that specific reaction. |
Get reactions
Example:
curl -X POST https://api.twist.com/api/v3/reactions/get \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d comment_id=206113
POST /api/v3/reactions/get
Gets reactions of a thread, comment or conversation message.
Parameters
Name | Required | Description |
---|---|---|
thread_id Integer | Yes, this or comment_id or message_id . |
The id of the thread. |
comment_id Integer | Yes, this or thread_id or message_id . |
The id of the comment. |
message_id Integer | Yes, this or thread_id or comment_id . |
The id of the conversation message. |
Return value
A reaction object is returned.
Add a reaction
Example:
curl -X POST https://api.twist.com/api/v3/reactions/add \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d reaction="π" \
-d comment_id=206113
POST /api/v3/reactions/add
Adds a reaction to a thread, comment or conversation message.
Parameters
Name | Required | Description |
---|---|---|
reaction String | Yes | The reaction to add. |
thread_id Integer | Yes, this or comment_id or message_id . |
The id of the thread. |
comment_id Integer | Yes, this or thread_id or message_id . |
The id of the comment. |
message_id Integer | Yes, this or thread_id or comment_id . |
The id of the conversation message. |
Return value:
{
"status": "ok"
}
Remove a reaction
Example:
curl -X POST https://api.twist.com/api/v3/reactions/remove \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d reaction="π" \
-d comment_id=206113
POST /api/v3/reactions/remove
Removes a reaction from thread, comment or conversation message.
Parameters
Name | Required | Description |
---|---|---|
reaction String | Yes | The reaction to remove. |
thread_id Integer | Yes, this or comment_id or message_id . |
The id of the thread. |
comment_id Integer | Yes, this or thread_id or message_id . |
The id of the comment. |
message_id Integer | Yes, this or thread_id or comment_id . |
The id of the conversation message. |
Return value:
{
"status": "ok"
}
Inbox
Inbox object:
[
{ "id": 38677, ... },
{ "id": 32038, ... },
...
]
The inbox unifies the start page view on all platforms.
It is actually a list of thread objects. It doesn’t contain all threads, but the most recent threads ordered by date.
Get inbox
Example:
curl --get https://api.twist.com/api/v3/inbox/get \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d workspace_id=5517
GET /api/v3/inbox/get
Parameters
Name | Required | Description |
---|---|---|
workspace_id Integer | Yes | The id of the workspace. |
limit Integer | No | Limits the number of threads returned, by default to 30 . |
newer_than_ts Integer | No | Limits threads to those newer when the specified Unix time. |
older_than_ts Integer | No | Limits threads to those older when the specified Unix time. |
Return value
A list of thread objects is returned.
Search
The search query allows for finding threads and conversations matching some text.
Search for query
Example:
curl --get https://api.twist.com/api/v3/search/query \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d query=texts
GET /api/v3/search/query
Return object:
{
"hits": 25,
"has_more": true,
"next_cursor_mark": "96e22dcb41564ab5802736b1d1e009d3",
"items": [
{
"obj_type": "thread",
"title": "Far far away",
"snippet": "It is a paradisematic country, in which roasted parts of sentences fly into your mouth.",
"details_link": "/api/v3/search/comments?query=texts&workspace_id=201&thread_id=401",
"id": 501,
"thread_id": 401,
"channel_id": 301,
"last_posted_ts": 1486726709,
"last_author": 101,
"participants": [ 101, 102, 103, 104 ],
"archived": false
},
{
"obj_type": "conversation",
"title": "Chat",
"snippet": "Even the all-powerful Pointing has no control about the blind texts...",
"details_link": "/api/v3/search/messages?query=texts&workspace_id=201&aggregate_id=123-345-678-9",
"id": 703,
"conversation_id": 601,
"last_author": 101,
"chunk_start_ts": 1486727013,
"chunk_end_ts": 1486727132,
"last_posted_ts": 1486727120,
"participants": [ 101, 105 ],
"user_ids": [ 101, 105],
"archived": false
}
]
}
Searches for a string.
Parameters
Name | Required | Description |
---|---|---|
query String | Yes | The full text query to search for. |
limit Integer | No | Limits the number of conversations. |
cursor_mark String | No | Token for pagination. |
Return object details
Name | Description |
---|---|
hits Integer | The number of results found. |
has_more Boolean | Whether there are more results that were not returned. |
next_cursor_mark String | The cursor mark to use in order to get more results. |
items List of Objects | The actual result items, threads or conversations found. |
obj_type String | The type of the item, a thread or a conversation. |
title String | The title of the item. |
snippet String | Part of the text that matched the search query. |
details_link String | A URL that can be used to get more details on the item. |
id Integer | The id of the comment or message. |
thread_id Integer | The id of the thread that the comment is part of. |
conversation_id Integer | The id of the conversation the message is part of. |
last_posted_ts Integer | The timestamp of the last post in the discussion. |
last_author Integer | The id of the last user that wrote in that discussion. |
participants List of Integers | The user ids that participate in that comment or message. |
user_ids List of Integers | The user ids that have joined that conversation. |
archived Boolean | Whether conversation or thread’s channel is archived. |
Get more details about comments
Example:
curl --get https://api.twist.com/api/v3/search/comments \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d query=texts \
-d workspace_id=201 \
-d thread_id=401"
GET /api/v3/search/comments
Return object:
{
"terms": [
"texts"
],
"items": [
{
"type": "thread",
"expanded": true,
"obj": {
"id": 501,
"last_obj_index": 3,
"title": "Far far away",
"content": "Far far away, behind the word mountains, far from the countries Vokalia and Consonantia, there live the blind texts.",
"snippet": "It is a paradisematic country, in which roasted parts of sentences fly into your mouth.",
"channel_id": 301,
"workspace_id": 201,
"creator": 101,
"snippet_creator": 101,
"comment_count": 4,
"posted": "2017-02-10 14:12:22",
"posted_ts": 1486735942,
"last_updated": "2017-02-10 14:14:36",
"last_updated_ts": 1486736076,
"is_starred": 0,
"attached_to_everyone": false,
"participants": [
101, 102, 103, 104
],
"recipients": [
101, 102, 103, 104
],
"groups": [],
"reactions": {},
"attachments": [],
},
},
{
"type": "comment_range",
"idx_start": 0,
"idx_end": 3,
"expand_link": "/api/v3/search/expand_comment_range?idx_end=3&thread_id=401&workspace_id=201&idx_start=0",
"top_expand_link": "/api/v3/search/expand_comment_range?idx_end=3&thread_id=401&workspace_id=201&idx_start=0&direction=top",
"bottom_expand_link": "/api/v3/search/expand_comment_range?idx_end=3&thread_id=401&workspace_id=201&idx_start=0&direction=bottom"
}
],
}
Here we get more details about a thread and its comments.
Expand comment range
Example:
curl --get https://api.twist.com/api/v3/search/expand_comment_range \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d idx_end=3 \
-d thread_id=401 \
-d workspace_id=201 \
-d idx_start=0
GET /api/v3/search/expand_comment_range
Return object:
{
"terms": [],
"items": [
{
"type": "comment",
"expanded": false,
"obj": {
"id": 164313,
"obj_index": 0,
"content": "Separated they live in Bookmarksgrove right at the coast of the Semantics, a large language ocean.",
"thread_id": 401,
"channel_id": 301,
"workspace_id": 201,
"creator": 102,
"posted": "2017-02-10 14:12:38",
"posted_ts": 1486735958,
"system_message": null,
"is_deleted": false,
"attached_to_everyone": false,
"groups": [],
"recipients": [
101, 102, 103, 104
],
"reactions": {},
"attachments": [],
},
},
...
]
The thread is expanded, that is more comments are returned.
Get more details about messages
Example:
curl --get https://api.twist.com/api/v3/search/messages \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d query=hello \
-d workspace_id=201 \
-d aggregate_id=123-345-678-9
GET /api/v3/search/messages
Return object:
{
"terms": [
"texts"
],
"items": [
{
"type": "conversation_message_range",
"idx_start": 0,
"idx_end": 5,
"expand_link": "/api/v3/search/expand_conversation_message_range?conversation_id=601&idx_end=5&workspace_id=201&idx_start=0",
"top_expand_link": "/api/v3/search/expand_conversation_message_range?conversation_id=601&idx_end=5&workspace_id=201&idx_start=0&direction=top",
"bottom_expand_link": "/api/v3/search/expand_conversation_message_range?conversation_id=601&idx_end=5&workspace_id=201&idx_start=0&direction=bottom",
},
{
"type": "conversation_message",
"expanded": false,
"obj": {
"obj_index": 6,
"content": "Pityful a rethoric question ran over her cheek, then she continued her way. On her way she met a copy",
"id": 702,
"conversation_id": 601,
"workspace_id": 201,
"creator": 105,
"posted_ts": 1486544628,
"reactions": {},
"attachments": [],
"actions": [],
"system_message": null,
"is_deleted": false,
},
},
{
"type": "conversation_message",
"expanded": true,
"obj": {
"obj_index": 7,
"content": "Even the all-powerful Pointing has no control about the blind texts it is an almost unorthographic life.",
"id": 703,
"conversation_id": 601,
"workspace_id": 201,
"creator": 101,
"posted_ts": 1486545169,
"reactions": {
"π": [
105
]
},
"attachments": [],
"actions": [],
"system_message": null,
"is_deleted": false,
},
},
{
"type": "conversation_message",
"expanded": false,
"obj": {
"obj_index": 8,
"content": "One day however a small line of blind text by the name of Lorem Ipsum decided to leave for the far World of Grammar.",
"id": 704,
"conversation_id": 601,
"workspace_id": 201,
"creator": 105,
"posted_ts": 1486545334,
"reactions": {
"π": [
101
]
},
"attachments": [],
"actions": [],
"system_message": null,
"is_deleted": false,
},
}
]
}
Here we get more details about a conversation and its messages.
Expand conversation message range
Example:
curl --get https://api.twist.com/api/v3/search/expand_conversation_message_range \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d conversation_id=601 \
-d idx_end=5 \
-d workspace_id=201 \
-d idx_start=0 \
-d direction=top
GET /api/v3/search/expand_conversation_message_range
Return object:
{
"terms": [],
"items": [
{
"type": "conversation_message",
"obj": {
"obj_index": 0,
"content": "She packed her seven versalia, put her initial into the belt and made herself on the way.",
"id": 701,
"conversation_id": 601,
"workspace_id": 201,
"creator": 105,
"posted_ts": 1458834794,
"reactions": {},
"attachments": [],
"actions": [],
"system_message": null,
"is_deleted": false,
},
},
...
],
}
The conversation is expanded, that is more comments are returned.
Notifications
The user’s last notifications.
Notification object:
{
"notifications": [
{
"id": 1,
"type_id": 1,
"workspace_id": 5517,
"channel_id": 6984,
"thread_id": 32038,
"comment_id": 206113,
"by_user_id": 10076,
"posted_ts": 1494489787,
}
],
"last_read": 0
}
Properties of notification object
Name | Description |
---|---|
id Integer | The id of the notification. |
type_id Integer | The notification type: 1 when added to a comment, 2 when added to a thread, 3 when added to a workspace, 4 when removed from a workspace, 5 when added to a channel, and 6 when removed from a channel. |
workspace_id Integer | The id of the workspace. |
channel_id Integer | The id of the channel. |
thread_id Integer | The id of the thread. |
comment_id Integer | The id of the comment. |
by_user_id Integer | The id of the user that triggered the notification (notified the receiving user). |
posted_ts Integer | The Unix time when the notification took place. |
last_read Integer | The id of the last read notification. |
Get last notifications
Example:
curl https://twist.com/api/v3/notifications/get \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf"
GET /api/v3/notifications/get
Gets the last notifications of the user.
Parameters
Name | Required | Description |
---|---|---|
limit Integer | No | Limits the number of threads returned. |
Return value
A list of notification objects is returned.
Mark notifications as read
Example:
curl -X POST https://twist.com/api/v3/notifications/mark_read \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf"
-d notification_id=1
POST /api/v3/notifications/mark_read
Marks everything after specified notification as read.
Parameters
Name | Required | Description |
---|---|---|
notification_id Integer | Yes | The last read notification id. |
Return value:
{
"status": "ok"
}
Reset notifications
Example:
curl -X POST https://twist.com/api/v3/notifications/reset \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf"
POST /api/v3/notifications/reset
Resets all notifications read status.
Return value:
{
"status": "ok"
}
Notifications settings
The user’s notification settings allow to setup email and push settings.
Notifications settings object:
{
"desktop_added_to_ws": true,
"desktop_comments": false,
"desktop_conversations": true,
"desktop_removed_from_ws": true,
"desktop_threads": false,
"email_added_to_ws": true,
"email_aggregate": true,
"email_comments": true,
"email_conversations": true,
"email_removed_from_ws": true,
"email_threads": true,
"push_added_to_ws": true,
"push_comments": false,
"push_conversations": true,
"push_delay": 120,
"push_removed_from_ws": true,
"push_threads": false,
"badge_conversations": true,
"badge_threads": true,
}
Properties of notifications settings object
Name | Description |
---|---|
desktop_conversations Boolean | Desktop notifications for new messages on conversations. |
desktop_comments Boolean | Desktop notifications for new comments attached to user. |
desktop_threads Boolean | Desktop notifications for new threads attached to user. |
desktop_added_to_ws Boolean | Desktop notifications when added to workspaces. |
desktop_removed_from_ws Boolean | Desktop notifications when removed from workspaces. |
email_conversations Boolean | Email notifications for new messages on conversations. |
email_comments Boolean | Email notifications for new comments attached to user. |
email_threads Boolean | Email notifications for new threads attached to user. |
email_added_to_ws Boolean | Email notifications when added to workspaces. |
email_removed_from_ws Boolean | Email notifications when removed from workspaces. |
email_aggregate Boolean | Email notifications digest. |
push_conversations Boolean | Push notifications for new messages on conversations. |
push_comments Boolean | Push notifications for new comments attached to user. |
push_delay Integer | Number of seconds before sending a push notification. |
push_threads Boolean | Push notifications for new threads attached to user. |
push_added_to_ws Boolean | Push notifications when added to workspaces. |
push_removed_from_ws Boolean | Push notifications when removed from workspaces. |
badge_threads Boolean | Badge notifications on unread threads (iOS). |
badge_conversations Boolean | Badge notifications on unread conversations (iOS). |
Get notification settings
Example:
curl --get https://api.twist.com/api/v3/notifications_settings/get \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d workspace_id=5517
GET /api/v3/notifications_settings/get
Gets the user’s current notification settings.
Parameters
Name | Required | Description |
---|---|---|
workspace_id Integer | Yes | The workspace id. |
Return value
A notifications settings object is returned.
Update notifications settings
Example:
curl -X POST https://api.twist.com/api/v3/notifications_settings/update \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d workspace_id=5517 \
-d setting=desktop_conversations \
-d value=true
POST /api/v3/notifications_settings/update
Return value:
{
"status": "ok"
}
Updates user notifications settings.
Parameters
Name | Required | Description |
---|---|---|
workspace_id Integer | Yes | The workspace id. |
setting String | Yes | The name of the notifications setting to update, see above. |
value Boolean | Yes | The value of the notifications setting to update. |
Update many notifications settings
Example:
curl -X POST https://api.twist.com/api/v3/notifications_settings/update_many \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d workspace_id=5517
-d mapping='{"desktop_conversations":true,"email_comments":false}'
POST /api/v3/notifications_settings/update_many
Return value:
{
"status": "ok"
}
Updates multiple user notifications settings at once.
Parameters
Name | Required | Description |
---|---|---|
workspace_id Integer | Yes | The workspace id. |
mapping Object | Yes | The notifications settings to update. |
URL join
This allows one to join a workspace using a special URL invite link.
URL join object:
{
"url": "https://twist.com/j/c5370f3ab4bad2d7eb6c432a17c37986"
}
Properties of URL join object
Name | Description |
---|---|
url String | The URL to be used to join a workspace. |
Get or create URL join link
Example:
curl -X POST https://api.twist.com/api/v3/url_join/get_or_create \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d workspace_id=5517
POST /api/v3/url_join/get_or_create
Gets or creates a URL join link to a workspace.
Parameters
Name | Required | Description |
---|---|---|
workspace_id Integer | Yes | The id of the workspace. |
Return value:
{
"url": "https://twist.com/j/c5370f3ab4bad2d7eb6c432a17c37986"
}
Disable URL join link
Example:
curl https://api.twist.com/api/v3/url_join/disable \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d workspace_id=5517
POST /api/v3/url_join/disable
Disables a URL join link to a workspace.
Parameters
Name | Required | Description |
---|---|---|
workspace_id Integer | Yes | The id of the workspace. |
Return value:
{
"status": "ok"
}
Join workspace
Example:
curl https://api.twist.com/api/v3/url_join/join_workspace \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d url_invite_code="https://twist.com/j/c5370f3ab4bad2d7eb6c432a17c37986"
POST /api/v3/url_join/join_workspace
Joins user to invited workspace using the URL link.
Parameters
Name | Required | Description |
---|---|---|
url_invite_code Integer | Yes | The URL join link. |
Return value
A workspace object is returned.
Loop in
This allows you to add threads to a channel, add comments to a thread, or messages to conversation by sending them to an email address.
Note: the maximum allowed size of the email is 25MB.
Loop in object:
{
"email": "https://twist.com/j/c5370f3ab4bad2d7eb6c432a17c37986"
}
Properties of URL join object
Name | Description |
---|---|
email String | The email address to use to add threads/comments/messages. |
Get or create a loop in email
Example:
curl -X POST https://api.twist.com/api/v3/loop_in/get_or_create \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d obj_type=THREAD \
-d obj_id=32038
POST /api/v3/loop_in/get_or_create
Gets or creates a loop in email.
Parameters
Name | Required | Description |
---|---|---|
obj_type String | Yes | The type of the object, one of CHANNEL , THREAD or CONVERSATION . |
obj_id Integer | Yes | The id of the object. |
Return value:
{
"email": "https://twist.com/j/c5370f3ab4bad2d7eb6c432a17c37986"
}
Disable loop in email
Example:
curl -X POST https://api.twist.com/api/v3/loop_in/disable \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d obj_type=THREAD \
-d obj_id=32038
POST /api/v3/loop_in/disable
Disables a loop in email.
Parameters
Name | Required | Description |
---|---|---|
obj_type String | Yes | The type of the object, one of CHANNEL , THREAD or CONVERSATION . |
obj_id Integer | Yes | The id of the object. |
Return value:
{
"status": "ok"
}
Integrations
Twist has multiple types of integrations, and you have to pick your type based on how your integration will be used. Here are links with the full explanation of each one with a small summary of what they can do:
- General Integration - Add features such as OAuth, bots, slash commands and composer extensions.
- Channel Updates - Has access to one channel and can post threads to it.
- Thread Updates - Has access to one thread and can post comments to it.
Use Channel Updates and Thread Updates when you need a quick way to post content to Twist. For example, our Github integration is a Thread Updates integration β it adds any Github activity as comments to a thread.
Channel Updates and Thread Updates include some special features such as buffering (not posting things in real-time) and scheduling (posting things at specific times).
HTTPS enforcing
Twist enforces HTTPS everywhere, including our production integrations. It means that all production URLs that communicate with Twist somehow have to use HTTPS. If you need a certificate, we highly recommend Let’s Encrypt. Furthermore, we also enforce certificate chain check.
General integration
The general integration is the most powerful one, and it lets you extend Twist in many ways.
You can add following features to your general integration:
- OAuth - Obtain access to user’s data in a secure way.
- Bot - Interacts with users conversationally using a bot.
- Slash Commands - Run your integration when the user types types
/command arguments
.
↳ OAuth
The OAuth feature lets you access user’s data in a secure way or setup webhooks. The general steps needed to setup are described in our OAuth2 section.
Example usage: Integrate an application with Twist, creating new workspaces, channels, threads, and/or messages.
Retrieving a token
Sometimes a developer just wants a token so he/she can use all the endpoints of the API for personal purposes or create a proof of concept. For these cases, when the OAuth integration is created we provide a test token.
The test token is a result of the OAuth2 process for the current logged user and will have the full scope access.
curl -X POST https://api.twist.com/api/v3/any_endpoint_of_this_doc \
-H "Authorization: Bearer Gen3rated_t3st_t0k3n" \
The generated token can be used in the authorization header to make requests to all endpoints in the API.
Outgoing webhook
Outgoing webhooks for OAuth integrations are based on REST hooks, so they are different from channels and threads.
The webhooks for the OAuth integration provide fine-grained access to the event hooks. It’s possible to subscribe and unsubscribe to any available event programmatically.
These are the supported events:
Event type | Description |
---|---|
workspace_added | Triggers when a workspace is added. |
workspace_updated | Triggers when a workspace is updated. |
workspace_deleted | Triggers when a workspace is deleted. |
workspace_user_added | Triggers when a user is added to a workspace. |
workspace_user_updated | Triggers when a user is updated inside a workspace. |
workspace_user_removed | Triggers when a user is removed from a workspace. |
channel_added | Triggers when a channel is added. |
channel_updated | Triggers when a channel is updated. |
channel_deleted | Triggers when a channel is deleted. |
channel_user_added | Triggers when a user is added to a channel. |
channel_user_updated | Triggers when a user is updated inside a channel. |
channel_user_removed | Triggers when a user is removed from a channel. |
thread_added | Triggers when a thread is added. |
thread_updated | Triggers when a thread is updated. |
thread_deleted | Triggers when a thread is deleted. |
comment_added | Triggers when a comment is added. |
comment_updated | Triggers when a comment is updated. |
comment_deleted | Triggers when a comment is deleted. |
message_added | Triggers when a message is added. |
message_updated | Triggers when a message is updated. |
message_deleted | Triggers when a message is deleted. |
group_added | Triggers when a group is added. |
group_updated | Triggers when a group is updated. |
group_deleted | Triggers when a group is deleted. |
group_user_added | Triggers when a user is added to a group. |
group_user_removed | Triggers when a user is removed from a group. |
Subscribe to a hook
Example
curl https://api.twist.com/api/v3/hooks/subscribe \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d target_url=https://hooks.yourdomain.com/<unique_target_url> \
-d event=workspace_user_added
To start listening to changes you have to subscribe to a hook. The following parameters are accepted in the subscribe request:
Name | Required | Description |
---|---|---|
target_url String | Yes | The URL we should call when an event happens. |
event_type String | Yes | What Twist event should trigger the call. |
workspace_id Integer | No | Only trigger for following workspace_id . |
channel_id Integer | No | Only trigger for following channel_id . |
thread_id Integer | No | Only trigger for following thread_id . |
conversation_id Integer | No | Only trigger for following conversation_id . |
It just needs to be done once, the target_url
will receive the
events until it receives an unsubscribe
command.
On a successful creation, Twist will return a 201 Created
and a 403
Forbidden
will be thrown if the access token scope does not have the
permission to subscribe to the specified event type.
When an event happens, we’ll send a request to your target_url
that
will be JSON encoded. The payload will be the object that triggered
the event, for example, channel_added
will
include the channel object.
Unsubscribe from a hook
Example
curl https://api.twist.com/api/v3/hooks/unsubscribe \
-H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
-d target_url=https://hooks.yourdomain.com/<unique_target_url>
To stop listening to changes just unsubscribe your hook. The following parameters are accepted:
Name | Required | Description |
---|---|---|
target_url String | Yes | The URL we should unsubscribe. |
On a successful unsubscribe, we return a 200 OK
.
↳ Bot
Add a bot user to your integration and interact with users conversationally.
Example usage: A internal support bot that helps your team serve customers better.
How a bot works
A bot is a user that will get added to a workspace as a guest when your integration gets installed.
Users can interact with the bot both using messages, but also via threads and comments. To communicate via threads and comments the bot needs to be part of the channel and needs to be a recipient.
Your bot will get removed from the workspace when your integration is uninstalled.
Outgoing webhook on bot activity
Note: Outgoing webhook for bots is different from the one provided by OAuth. π
We’ll send an outgoing webhook whenever your bot is messaged (e.g., a new comment is added, and the bot is one of the recipients).
It sends an HTTPS POST request to your specified URL and your webhook handler can respond to add data back to Twist.
The outgoing hooks can work with any language or framework β as long as they support HTTPS and JSON.
You don’t need to respond right away; you can also post a request to the url_callback
that is provided via the payload.
Simply respond with 202 Accepted
and return an empty body to trigger a delayed response.
url_callback
is only valid for 30 minutes, please inspect url_ttl
to ensure that it’s still valid.
POST form parameters when users add new objects
When a new message, thread or a new comment is added, you can expect following default parameters.
Name | Description |
---|---|
event_type String | Can be message , thread or comment β depending where the bot was contacted. |
workspace_id Integer | The workspace the object was posted in. |
content String | The content of object, e.g. thread or message content. |
user_id Integer | The id of the poster. |
user_name String | The name of the poster. |
url_callback String | An URL you can use to delay the response from the bot. |
url_ttl Integer | Unix timestamp of when url_callback expires. |
When event_type
is thread
or channel
, we’ll also send these fields:
Name | Description |
---|---|
thread_id Integer | id of the thread |
thread_title String | title of the thread |
channel_id Integer | id of the channel which the thread is part of |
When event_type
is message
, we’ll also send these fields:
Name | Description |
---|---|
comment_id Integer | id of the comment |
conversation_title String | Title of the conversation |
POST form parameters for a ping
For debugging purposes, you might get a ping
payload. You should respond back
with a JSON {"content": "pong"}
.
Name | Optional | Description |
---|---|---|
event_type String | No | Will be ping . |
user_id Integer | No | The id of the pinger. |
user_name String | No | The full name of the pinger. |
Adding content back
If your handler wishes to post a response back, use the following JSON response:
{"content": "42 is the answer to everything."}
Error handling
Non-2xx responses will be retried 3 times in the span of 30 minutes.
↳ Slash Commands
Slash commands are installed on a workspace level. When a user types /command arguments
your integration runs and can act upon the arguments.
Examples: /gif funny cats
is a slash command. Another example is
the appear.in integration, which lets you easily
schedule video meetings (/appearin meeting-room
). Both integrations
are available on
our integrations page.
As slash commands can be used in different contexts (i.e. inside of a thread or conversation), the return may be different depending on where it is used. You can see the differences in the below example.
Example implementation
Thread
# formstring data
user_name: user_name
verify_token: 200_abcdefghijklmnopqrstuvwx
thread_id: 180000
workspace_id: 4800
command_argument: appearin_username
command: /appear
thread_title: Test thread name
content: /appear appearin_username
event_type: comment
comment_id: 6402000
channel_name: General
channel_id: 6000
user_id: 9000
Conversation
# formstring data
user_id: 9000,
event_type: message,
conversation_title: conversation_title,
verify_token: 200_abcdefghijklmnopqrstuvwx,
content: /appear username,
command: /appear,
conversation_id: 296779,
command_argument: username,
user_name: John D.,
message_id: 3456789,
workspace_id: 1234
# JSON return
{
"content": "πΉ [/appear appearin_username](https://appear.in/appearin_username)"
}
You can check some examples in the integration examples repository. Let’s use the python example implementation for the appear.in an example.
Your application will receive a POST call with some information in a
formstring format, so the integration can decide what to do and it
replies with a JSON containing a content
key. The text on this
content
key will replace the message containing the slash command.
Timeout
Be aware that your integration must deliver the content in less than 10 seconds or the server will drop the connection and try again as stated in Error handling.
Get all
Retrieves a full list of Slash commands for a team.
POST Parameters
Name | Required | Description |
---|---|---|
workspace_id Integer | Yes | The id of the workspace. |
curl https://api.twist.com/api/v3/slash_commands/get \
-H "Authorization: Bearer 9b1bf97733c1ad5593cee12f3029079ddd3042cf" \
-d workspace_id=1881
Return value:
[
{
"integration_id": 1820,
"id": 20,
"command": "/gif",
"description": "Share an emotion using a gif",
"usage_help": "cats"
}
]
Return value
Name | Description |
---|---|
integration_id Integer | The id of the integration. |
id Integer | The id of the slash command |
command String | The command used to activate the slash command |
description String | A description of the slash command |
usage_help String | A typical example of how to use the slash command |
Channel Updates
Channel Updates integrations are installed on a channel level and can post new threads.
It provides an URL for distribution and installation, so the integration developer can provide it to his users. The installation page asks for write permission to one channel and also which teams it should notify. In case the schedule option was used, it will also ask for the recurrence period and source of data.
Example usage: A growth report that Twist posts on a weekly or monthly basis to the same channel.
Incoming webhook
Sometimes a developer just wants an incoming webhook URL to post
via manually via curl
(for example) or to include in the Continuous
Integration build. It can be done via OAuth integration by
using the token provided or via channel or thread integration.
To do that using a channel integration, you just have to create and install it. After the installation, Twist will provide the URL for manual posting.
Please follow the subsection on How to post data from a channel integration.
Outgoing webhook
Note: Outgoing webhook for channels is really different from the one provided by OAuth. π
Outgoing webhooks send data when an activity happens (e.g. a new comment is added to the thread or an uninstall happens).
It sends an HTTPS POST request to your specified URL and your webhook handler can respond to add data back to Twist. The payload depends on the integration type.
The outgoing hooks can work with any language or framework β as long as they support HTTPS and JSON.
POST Parameters when users add new objects
When a new message, thread or a new comment is added, you can expect following parameters.
Name | Optional | Description |
---|---|---|
event_type String | No | Can be message , thread or comment β depending where the slash command was used. |
workspace_id Integer | No | The workspace the object was posted in. |
content String | No | The content of object, e.g. thread or message content. |
user_id Integer | No | The id of the poster. |
user_name String | No | The name of the poster. |
conversation_id Integer | Yes | Will be set if event_type is message . |
conversation_title String | Yes | Will be set if event_type is message . |
thread_id Integer | Yes | Will be set if event_type is thread or comment . |
thread_title String | Yes | Will be set if event_type is thread or comment . |
channel_id Integer | Yes | Will be set if event_type is thread or comment . |
comment_id Integer | Yes | Will be set if event_type is comment . |
command String | Yes | If the integration type is a slash command we’ll include the command, e.g. /hello . |
command_argument String | Yes | If the integration type is a slash command we’ll include the command argument, e.g. for /hello world it would be world . |
POST Parameters when an uninstall happens
When a team uninstalls your integration, you can expect the following parameters. You can use this to clean up any state you may have on your end.
Name | Optional | Description |
---|---|---|
event_type String | No | Will be uninstall . |
install_id Integer | No | The unique id of the installation. |
workspace_id Integer | No | The workspace the installation belonged to. |
user_id Integer | No | The id of the uninstaller. |
user_name String | No | The full name of the uninstaller. |
POST Parameters when a ping happens
For debugging purposes, you might get a ping
payload. You should respond back
with a JSON {"content": "pong"}
.
Name | Optional | Description |
---|---|---|
event_type String | No | Will be ping . |
user_id Integer | No | The id of the pinger. |
user_name String | No | The full name of the pinger. |
Adding content back
If your handler wishes to post a response back, use the following JSON response:
{"content": "42 is the answer to everything."}
Error handling
Non-200 responses will be retried 10 times in the span of 12 hours.
Configure URL
We redirect users to the configure URL when setting up the integration. The configured URL lets you connect the installation to your app and also includes an incoming webhook URL, which you can use as an easy way to manually post new threads into Twist as an integration.
You’ll get following GET parameters served to your configure URL:
GET Parameters
Name | Required | Description |
---|---|---|
install_id Integer | Yes | The unique id of the installation. |
post_data_url String | Yes | A unique URL you can use to post content to Twist. |
user_id Integer | Yes | The id of the installer. |
user_name String | Yes | The full name of the installer. |
To get back to the installation page, please use
https://twist.com/integrations/installation/{install_id}
.
How to post data from a channel integration
CURL example
curl -X POST -H 'Content-type: application/json' \
--data '{"content":"42?"}' \
"https://hooks.twist.com/api/v3/integration_incoming/post_data?install_id=...&install_token=..."
Simply make a POST request to the post_data_url
. In the POST include your data
encoded in JSON.
POST Parameters
Name | Required | Description |
---|---|---|
content String | Yes | The content of the new object. |
title String | No | Title of the new thread. |
URL Reports
This feature provides a way to retrieve real content from an external source via
GET request. When combined with the schedule
feature may become a way to
provide periodic information with real data.
Returning Markdown content
Automatic URL Reports can return plain Markdown content and Twist will use it as content for the new thread.
For example, the URL can return following (e.g. to generate automatic growth reports):
Apple today announced financial results for its fiscal 2017 second quarter ended April 1, 2017.
Core numbers:
* $78.4 Billion Revenue
* 78.3 Million iPhones
* 13.1 Million iPads Sold
* ...
Returning JSON content
The URL content can also return a JSON object specifying title
and content
of the new thread.
Content-type: application/json
{
"title": "Webdev snippets | <date>",
"content": "Please share your weeky snippets"
}
Note that you can use <date>
in the title
, and we will convert it to the
current date.
Thread Updates
Thread Updates integration is installed on a thread level, and they can post new comments.
It provides an URL for distribution and installation, so the integration developer can provide it to his users. The installation page asks for write permission to one channel or thread and which teams it should notify.
Example usage: Post comments when new issues are added to a GitHub repository.
Incoming webhook
Sometimes a developer just want an incoming webhook URL to post via some script or external system without setting up a webserver and so on. It can be done via OAuth integration by using the token provided or via channel or thread integration.
To do that using a thread integration, you just have to create and install it. After the installation, Twist will provide the URL for manual posting.
Please follow the subsection on How to post data from a thread integration.
Outgoing webhook
Note: Outgoing webhook for threads is really different from the one provided by OAuth. π
Outgoing webhooks send data when an activity happens (e.g. a new comment is added to the thread or an uninstall happens).
It sends an HTTPS POST request to your specified URL and your webhook handler can respond to add data back to Twist. The payload depends on the integration type.
The outgoing hooks can work with any language or framework β as long as they support HTTPS and JSON.
POST Parameters when users add new objects
When a new message, thread or a new comment is added, you can expect following parameters.
Name | Optional | Description |
---|---|---|
event_type String | No | Can be message , thread or comment β depending where the slash command was used. |
workspace_id Integer | No | The workspace the object was posted in. |
content String | No | The content of object, e.g. thread or message content. |
user_id Integer | No | The id of the poster. |
user_name String | No | The name of the poster. |
conversation_id Integer | Yes | Will be set if event_type is message . |
conversation_title String | Yes | Will be set if event_type is message . |
thread_id Integer | Yes | Will be set if event_type is thread or comment . |
thread_title String | Yes | Will be set if event_type is thread or comment . |
channel_id Integer | Yes | Will be set if event_type is thread or comment . |
comment_id Integer | Yes | Will be set if event_type is comment . |
command String | Yes | If the integration type is a slash command we’ll include the command, e.g. /hello . |
command_argument String | Yes | If the integration type is a slash command we’ll include the command argument, e.g. for /hello world it would be world . |
POST Parameters when an uninstall happens
When a team uninstalls your integration, you can expect following parameters. You can use this to clean up any state you may have on your end.
Name | Optional | Description |
---|---|---|
event_type String | No | Will be uninstall . |
install_id Integer | No | The unique id of the installation. |
workspace_id Integer | No | The workspace the installation belonged to. |
user_id Integer | No | The id of the uninstaller. |
user_name String | No | The full name of the uninstaller. |
POST Parameters when a ping happens
For debugging purposes, you might get a ping
payload. You should respond back
with a JSON {"content": "pong"}
.
Name | Optional | Description |
---|---|---|
event_type String | No | Will be ping . |
user_id Integer | No | The id of the pinger. |
user_name String | No | The full name of the pinger. |
Adding content back
If your handler wishes to post a response back, use the following JSON response:
{"content": "42 is the answer to everything."}
Error handling
Non-200 responses will be retried 10 times in the span of 12 hours.
Configure URL
We redirect users to the configure URL when setting up the integration. The configured URL lets you connect the installation with your app and also includes an incoming webhook URL, which you can use as an easy way to post messages into Twist.
You’ll get following GET parameters served to your configure URL:
GET Parameters
Name | Required | Description |
---|---|---|
install_id Integer | Yes | The unique id of the installation. |
post_data_url String | Yes | A unique URL you can use to post content to Twist. |
user_id Integer | Yes | The id of the installer. |
user_name String | Yes | The full name of the installer. |
To get back to the installation page, please use
https://twist.com/integrations/installation/{install_id}
.
How to post data from a thread integration
CURL example
curl -X POST -H 'Content-type: application/json' \
--data '{"content":"42?"}' \
"https://hooks.twist.com/api/v3/integration_incoming/post_data?install_id=...&install_token=..."
Simply make a POST request to the post_data_url
. In the POST include your data
encoded in JSON.
POST Parameters
Name | Required | Description |
---|---|---|
content String | Yes | The content of the new object. |
Bot tutorial
In this tutorial, we’ll create a Twist bot using Node.js. Our bot will be able to respond to new threads, comments, and private messages.
Prerequisites
Although this tutorial is based on Node and JavaScript, the concepts can be applied to other languages and frameworks.
We’ll need the following tools:
New project
Start off by creating a new Node.js and Express application.
To create a new Node project, run the following in your terminal:
# Create a new directory
$ mkdir twist-bot
# Change directory
$ cd twist-bot
# Initiate a new Node project
$ npm init -y
# Create a bot.js file
$ touch bot.js
Install the required dependencies
Next up, we’ll need to install express
and body-parser
to our project.
# Install project dependencies
$ npm install express body-parser
Server Setup
const express = require('express');
const bodyParser = require('body-parser');
const app = express();
// Parse POST requests with JSON or URLEncoded
app.use(bodyParser.json());
app.use(
bodyParser.urlencoded({
extended: true,
}),
);
app.listen(process.env.PORT || 3000, () =>
console.log(`Server listening on port ${process.env.PORT || 3000}`),
);
We can set up a listen server with Express. This allows us to define our own routes and react to incoming events.
Nodemon
# Install nodemon globally
$ npm install nodemon -g
# Run our server with nodemon.
$ nodemon bot.js
We can then run our project using nodemon
. This means any changes to our code will restart our Node server, allowing for a much smoother development experience.
Run the following in your terminal:
Webhooks
app.post('/bot', (req, res) => {
const body = req.body;
console.log(body);
});
We can then define a new route that our Webhook will point at. This means any time that the bot is interacted with, the request will be pointed toward this endpoint.
Currently, this route is defined but not used. We’ll need to expose our application and create an integration/webhook based on user events. We can simply log out the body
to see a typical interaction example once our integration has been created.
We won’t be able to see the results of this until we create an integration on Twist and make a test event. Let’s do that next!
New Twist integration
Navigate to your Twist team and select “Add Integrations” from the top-right dropdown menu.
From here, we’ll be taken to the integrations dashboard. This shows us all the available integrations for our Twist team, as well as the ability to manage and create new ones.
To create a new Twist integration, select “Build” from the navigation menu and then “Add new integration”. We can then select “General Integration” and fill out appropriate project information.
Select “Create my integration” to finish the process.
We’re then navigated to the integration details screen, giving us the ability to add extra functionality with “Composer Extensions”, “OAuth Authentication”, and more. As we’re only looking to have “Bot” functionality for now, select “Bot”.
We now need to provide an Outgoing Webhook URL which will listen for incoming Twist events. This is where ngrok
and our Node project comes in.
Inside of a new terminal window (but the same directory), run the following:
$ ngrok http 3000
# Endpoint URL
https://00b570fe.eu.ngrok.io/bot
This gives us the ability to test our bot without having to upload the code to a web server. Within the “Bot” part of your integration settings, add the Forwarding URL to the Outgoing Webhook URL field, ensuring to add the /bot/
endpoint that we created earlier.
To test everything works as intended, select the “Test ping URL” button. This should send a request to our /bot/
route and log out the request body inside of our terminal.
A typical response will look like this:
{ event_type: 'ping', verify_token: '221_3c2c24332bbcd3cd22dec12' }
app.post('/bot', (req, res) => {
const body = req.body;
console.log(body);
if (body.event_type === 'ping') {
res.json({ content: 'pong' });
}
});
As this is a debugging payload, we’ll respond with { content: 'pong' }
.
If we click the “Test ping URL” button once again, you’ll notice that we can see the “pong” payload that we sent back as an alert within the browser.
Event types
So far we’ve got ourselves a bot that exists, but doesn’t say (or do) anything. We can choose to add functionality to our bot by first determining the type of communication.
The event_type
response will be different depending on the context:
Event type | Description |
---|---|
ping | Used for debugging purposes. |
thread | Appears whenever the bot is notified in a new thread. |
comment | Appears whenever the bot is mentioned in a comment. |
message | Appears whenever the bot is messaged. |
We can therefore use this to send personalised responses or actions depending on the type of user interaction.
Responding to users
const handleMessage = body => {
switch (body.event_type) {
case `ping`:
return { content: `pong` };
break;
case `thread`:
return `Thanks for notifying me of this thread!`;
break;
case `comment`:
return `Interesting you should mention that. I was thinking the same thing!`;
break;
case `message`:
return `Hello ${body.user_name}! I hope you're having a great day.`;
break;
default:
return { content: `` };
break;
}
};
app.post('/bot', (req, res) => {
const body = req.body;
const response = handleMessage(body);
res.send(response);
});
Similar to responding to the ping
requests, we can take advantage of the thread
, comment
, and message
event types to apply context to our bot.
Therefore, by responding to these events, our resulting action(s) become the following:
Event type | Action |
---|---|
Notified in a new thread | “Thanks for notifying me of this thread!” |
Mentioned in a comment | “Interesting you should mention that. I was thinking the same thing!”. |
Direct message | “Hello Paul! I hope you’re having a great day”. |
Migrating from v2 to v3
This guide outlines the key differences between version 2
and 3
of the Twist API.
The new v3
Twist API is largely based on the v2
API. Most changes are simply done by changing the URL from /v2/
to /v3
.
Below are the breaking changes made during the transition between v2
and v3
.
User
is_bot
is nowbot
.is_removed
is nowremoved
.
Threads
last_updated
is deprecated.is_starred
is nowstarred
.
Comment
is_deleted
is nowdeleted
.
Conversations
snippet_creator
is deprecated.message_count
is deprecated.name
is deprecated.is_private
is nowprivate
.- A
last_message
object has been added which shows information about the last message, such as thecreator
,content
,attachments
and more.
Conversation Message
is_deleted
is nowdeleted
.