NAV Navbar

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

You can login via /api/v3/users/login and retrieve your user token. 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:

Dates

For dates we use ISO 8601. The formatting we can have inside the system:

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.

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:

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. A workspace user has less attributes than the current logged user because it represents the public information other users can see from them.

Workspace user object:

curl -X POST https://api.twist.com/api/v3/workspaces/get_users \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d id=5517

Example workspace user response json { "avatar_id": null, "away_mode": { "date_from": "2019-03-19", "type": "vacation", "date_to": "2019-04-01" } "bot": false, "contact_info": "", "date_format": "MM/DD/YYYY", "email": "librarian@doist.com", "feature_flags": [ "all" ], "first_name": "Librarian", "id": 200000, "name": "Librarian Doe", "profession": "Writing and keeping docs", "removed": true, "restricted": false, "setup_pending": false, "short_name": "Librarian D.", "time_format": "12", "timezone": "UTC", "user_type": "USER" }

Properties of workspace user object

Name Description
avatar_id String A hash used to find the avatar image.
away_mode Object Away mode sets the user as away until some future date. See User for more details.
bot Boolean Whether user is a bot.
date_format String The format the date is displayed. Example: MM/DD/YYYY.
email String The user’s email.
feature_flags List of String A list of features that are enabled, mostly used for official apps.
first_name String The user’s first name.
id Integer The id of the user.
name String The user’s full name.
profession String The user’s profession.
removed Boolean Whether the user has been removed.
restricted Boolean Whether the user is restricted.
setup_pending Integer/Boolean Whether setup is pending.
short_name String The user’s short name.
time_format String The format the time should be displayed. It can be 12 or 24.
timezone Integer The user’s timezone.
user_type String Yes

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.

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"
}

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:

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

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 for channels

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 for channels

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 for threads

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 for threads

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.

Add integrations

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.

Integrations dashboard

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.

New integration

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”.

Bot settings

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

Ngrok

# 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.

Endpoint

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.

Pong response

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

Threads

Comment

Conversations

Conversation Message