Introduction

This is the official Twist API v3 documentation, a reference to the functionality our public API provides, with detailed description of each API endpoint, its parameters, and examples.

Authentication

Login and signup are done via /api/v3/users/login and /api/v3/users/register. For public integration, you must use our OAuth 2 authentication.

If you just want a token to try the API, we provide a test token when you create an application following what we describe in the OAuth 2 authentication guide.

Temporary ids

Temporary ids are negative and can be used when adding, updating or deleting items.

Request, response, and error handling

The maximum allowed size of the request body for common requests is 5MB. Some attachments have their own limits for upload, please check their own sections for more details.

A response is always a JSON object which can be the following:

On successful return: JSON data.
On an error return, HTTP error code followed by: {“error”: [error_code, error_string], **kwargs}.

Dates

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

Date time: %Y-%m-%d %H:%M:%S.
Date only: %Y-%m-%d.
With timezone info: %Y-%m-%d %H:%M:%S +00:00.

The current API should only return %Y-%m-%d %H:%M:%S, where the time zone is implicit set to UTC.

Errors

Errors will be returned as JSON objects.

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

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

[
  {
    "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.

{
  "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.

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

curl -X POST https://api.twist.com/api/v3/users/logout

POST /api/v3/users/logout

{
   "status": "ok"
}

Logs out user, and resets the session.

Register

curl -X POST https://api.twist.com/api/v3/users/register \
  -d name=User \
  -d email=user@example.com \
  -d password=secret

POST /api/v3/users/register

Parameters

Name	Required	Description
name String	Yes	The user’s full name.
email String	Yes	The user’s email.
password String	Yes	The user’s password.

Return value

The user object.

Update

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

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

curl -X POST https://api.twist.com/api/v3/users/update_avatar \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -F image=@avatar.jpg

POST /api/v3/users/update_avatar

Updates user’s avatar. It currently supports the following formats:

gif
jpeg
png
bmp
tiff

Note: the maximum allowed size for the avatar is 10MB

Parameters

Name	Required	Description
image String	Yes	Avatar image uploaded as `multipart/form-data`.

Return value

The updated user object is returned.

Invalidate token

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

curl -X POST https://api.twist.com/api/v3/users/validate_token \
  -d token=9b1bf97783c1ad5593dee12f3019079dbd3042cf

POST /api/v3/users/validate_token

{
   "status": "ok"
}

Validates the user token.

Set presence

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

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

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

{
   "status": "ok"
}

Marks user as inactive on workspace.

Parameters

Name	Required	Description
workspace_id Integer	Yes	The id of the workspace.

Reset password

curl -X POST https://api.twist.com/api/v3/users/reset_password \
  -d email=user@example.com

POST /api/v3/users/reset_password

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

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

curl https://api.twist.com/api/v3/users/is_connected_to_google \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \

GET /api/v3/users/is_connected_to_google

{
   "google_connection": true,
   "google_email": "amix4k@gmail.com"
}

Checks whether user’s account is connected to a Google account.

Disconnect from Google

curl -X POST https://api.twist.com/api/v3/users/disconnect_google \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \

POST /api/v3/users/disconnect_google

{
   "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.

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

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

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

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

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

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

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

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

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

"user": {
   "id": 10073,
   "email": "user1@example.com",
   "name": "User1",
   "short_name": "User1",
   "avatar_id": "c5f14f4da3ee2479a26c65c630c21765",
   "default_workspace": null,
   "profession": "",
   "contact_info": "",
   "timezone": "UTC",
   "snooze_until": -1,
   "snooze_dnd_start": null,
   "snooze_dnd_end": null,
   "away_mode": null,
   "off_days": [],
   "setup_pending": 0,
   "is_bot": 0,
   "user_type": "ADMIN",
   "is_removed": 0,
   "is_doist_employee": 0,
}

Properties of workspace user object

Name	Description
user_type String	The user type, one of `ADMIN`, `USER` or `GUEST`.
is_removed Boolean	Whether the user has been removed.
is_doist_employee Boolean	Whether the user is a Doist employee.

Add user

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

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

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

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

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

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

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

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

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

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

"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

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.

[
  {
    "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.

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

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

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

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

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

curl -X POST https://api.twist.com/api/v3/groups/remove \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \ 
  -d id=498

POST /api/v3/groups/remove

{
   "status": "ok"
}

Removes a group.

Parameters

Name	Required	Description
id Integer	Yes	The id of the group.

Add user

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

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

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

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

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

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

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

{
   "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.

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

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

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

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

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

curl -X POST https://api.twist.com/api/v3/channels/archive \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d id=6984

POST /api/v3/channels/archive

{
   "status": "ok"
}

Archives a channel.

Parameters

Name	Required	Description
id Integer	Yes	The id of the channel.

Unarchive channel

curl -X POST https://api.twist.com/api/v3/channels/unarchive \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d id=6984

POST /api/v3/channels/unarchive

{
   "status": "ok"
}

Unarchives a channel.

Parameters

Name	Required	Description
id Integer	Yes	The id of the channel.

Remove channel

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

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

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

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

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

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

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

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

{
   "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.

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

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

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

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

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

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

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.

{
   "status": "ok"
}

Unstar thread

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.

{
   "status": "ok"
}

Move thread

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.

{
   "status": "ok"
}

Follow thread

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.

{
   "status": "ok"
}

Unfollow thread

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.

{
   "status": "ok"
}

Get unread threads

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.

[
    [
        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

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.

{
   "status": "ok"
}

Mark thread as unread

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.

{
   "status": "ok"
}

Mark all threads as read

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.

{
   "status": "ok"
}

Clear unread threads

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.

{
   "status": "ok"
}

Mute thread

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

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.

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

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

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

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

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

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.

{
   "status": "ok"
}

Mark position

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.

{
   "status": "ok"
}

Conversations

A conversation is a direct message exchange between one or more users.

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

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

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

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

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

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.

{
   "status": "ok"
}

Add users

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.

{
   "status": "ok"
}

Remove user

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.

{
   "status": "ok"
}

Remove users

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.

{
   "status": "ok"
}

Archive conversation

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.

{
   "status": "ok"
}

Unarchive conversation

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.

{
   "status": "ok"
}

Get unread conversations

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

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

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.

{
   "status": "ok"
}

Mark conversation as unread

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.

{
   "status": "ok"
}

Mute conversation

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

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.

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

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

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

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

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

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.

{
   "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.

{
    ...,

    "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

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

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

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.

{
   "status": "ok"
}

Reactions

Reactions can be added to threads, comments or conversation messages.

{
   "👍": [
      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

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

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.

{
   "status": "ok"
}

Remove a reaction

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.

{
   "status": "ok"
}

Inbox

[
   {    "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

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

curl --get https://api.twist.com/api/v3/search/query \
    -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
    -d query=texts

GET /api/v3/search/query

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

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

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

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

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

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

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

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

{
  "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.

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

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

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.

{
   "status": "ok"
}

Reset notifications

curl -X POST https://twist.com/api/v3/notifications/reset \
    -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf"

POST /api/v3/notifications/reset

Resets all notifications read status.

{
   "status": "ok"
}

Notifications settings

The user’s notification settings allow to setup email and push settings.

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

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

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

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

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

{
   "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": "https://twist.com/j/c5370f3ab4bad2d7eb6c432a17c37986"
}

Properties of URL join object

Name	Description
url String	The URL to be used to join a workspace.

Get or create URL join link

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.

{
   "url": "https://twist.com/j/c5370f3ab4bad2d7eb6c432a17c37986"
}

Disable URL join link

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.

{
   "status": "ok"
}

Join workspace

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.

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

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.

{
   "email": "https://twist.com/j/c5370f3ab4bad2d7eb6c432a17c37986"
}

Disable loop in email

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.

{
   "status": "ok"
}

Integrations

Twist has multiple types of integrations, and you have to pick your type based on how your integration will be used. Here are links with the full explanation of each one with a small summary of what they can do:

General Integration - Add features such as OAuth, bots, slash commands and composer extensions.
Channel Updates - Has access to one channel and can post threads to it.
Thread Updates - Has access to one thread and can post comments to it.

Use Channel Updates and Thread Updates when you need a quick way to post content to Twist. For example, our Github integration is a Thread Updates integration — it adds any Github activity as comments to a thread.

Channel Updates and Thread Updates include some special features such as buffering (not posting things in real-time) and scheduling (posting things at specific times).

HTTPS enforcing

Twist enforces HTTPS everywhere, including our production integrations. It means that all production URLs that communicate with Twist somehow have to use HTTPS. If you need a certificate, we highly recommend Let’s Encrypt. Furthermore, we also enforce certificate chain check.

General integration

The general integration is the most powerful one, and it lets you extend Twist in many ways.

You can add following features to your general integration:

OAuth - Obtain access to user’s data in a secure way.
Bot - Interacts with users conversationally using a bot.
Slash Commands - Run your integration when the user types types /command arguments.

↳ OAuth

The OAuth feature lets you access user’s data in a secure way or setup webhooks. The general steps needed to setup are described in our OAuth2 section.

Example usage: Integrate an application with Twist, creating new workspaces, channels, threads, and/or messages.

Retrieving a token

Sometimes a developer just wants a token so he/she can use all the endpoints of the API for personal purposes or create a proof of concept. For these cases, when the OAuth integration is created we provide a test token.

The test token is a result of the OAuth2 process for the current logged user and will have the full scope access.

curl -X POST https://api.twist.com/api/v3/any_endpoint_of_this_doc \
  -H "Authorization: Bearer Gen3rated_t3st_t0k3n" \

The generated token can be used in the authorization header to make requests to all endpoints in the API.

Outgoing webhook

Outgoing webhooks for OAuth integrations are based on REST hooks, so they are different from channels and threads.

The webhooks for the OAuth integration provide fine-grained access to the event hooks. It’s possible to subscribe and unsubscribe to any available event programmatically.

These are the supported events:

Event type	Description
workspace_added	Triggers when a workspace is added.
workspace_updated	Triggers when a workspace is updated.
workspace_deleted	Triggers when a workspace is deleted.
workspace_user_added	Triggers when a user is added to a workspace.
workspace_user_updated	Triggers when a user is updated inside a workspace.
workspace_user_removed	Triggers when a user is removed from a workspace.
channel_added	Triggers when a channel is added.
channel_updated	Triggers when a channel is updated.
channel_deleted	Triggers when a channel is deleted.
channel_user_added	Triggers when a user is added to a channel.
channel_user_updated	Triggers when a user is updated inside a channel.
channel_user_removed	Triggers when a user is removed from a channel.
thread_added	Triggers when a thread is added.
thread_updated	Triggers when a thread is updated.
thread_deleted	Triggers when a thread is deleted.
comment_added	Triggers when a comment is added.
comment_updated	Triggers when a comment is updated.
comment_deleted	Triggers when a comment is deleted.
message_added	Triggers when a message is added.
message_updated	Triggers when a message is updated.
message_deleted	Triggers when a message is deleted.
group_added	Triggers when a group is added.
group_updated	Triggers when a group is updated.
group_deleted	Triggers when a group is deleted.
group_user_added	Triggers when a user is added to a group.
group_user_removed	Triggers when a user is removed from a group.

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

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

# 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

# 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

[
  {
    "integration_id": 1820,
    "id": 20,
    "command": "/gif",
    "description": "Share an emotion using a gif",
    "usage_help": "cats"
  }
]

Return value

Name	Description
integration_id Integer	The id of the integration.
id Integer	The id of the slash command
command String	The command used to activate the slash command
description String	A description of the slash command
usage_help String	A typical example of how to use the slash command

Channel Updates

Channel Updates integrations are installed on a channel level and can post new threads.

It provides an URL for distribution and installation, so the integration developer can provide it to his users. The installation page asks for write permission to one channel and also which teams it should notify. In case the schedule option was used, it will also ask for the recurrence period and source of data.

Example usage: A growth report that Twist posts on a weekly or monthly basis to the same channel.

Incoming webhook

Sometimes a developer just wants an incoming webhook URL to post via manually via curl (for example) or to include in the Continuous Integration build. It can be done via OAuth integration by using the token provided or via channel or thread integration.

To do that using a channel integration, you just have to create and install it. After the installation, Twist will provide the URL for manual posting.

Please follow the subsection on How to post data from a channel integration.

Outgoing webhook

Note: Outgoing webhook for channels is really different from the one provided by OAuth. 😉

Outgoing webhooks send data when an activity happens (e.g. a new comment is added to the thread or an uninstall happens).

It sends an HTTPS POST request to your specified URL and your webhook handler can respond to add data back to Twist. The payload depends on the integration type.

The outgoing hooks can work with any language or framework — as long as they support HTTPS and JSON.

POST Parameters when users add new objects

When a new message, thread or a new comment is added, you can expect following parameters.

Name	Optional	Description
event_type String	No	Can be `message`, `thread` or `comment` — depending where the slash command was used.
workspace_id Integer	No	The workspace the object was posted in.
content String	No	The content of object, e.g. thread or message content.
user_id Integer	No	The id of the poster.
user_name String	No	The name of the poster.
conversation_id Integer	Yes	Will be set if `event_type` is `message`.
conversation_title String	Yes	Will be set if `event_type` is `message`.
thread_id Integer	Yes	Will be set if `event_type` is `thread` or `comment`.
thread_title String	Yes	Will be set if `event_type` is `thread` or `comment`.
channel_id Integer	Yes	Will be set if `event_type` is `thread` or `comment`.
comment_id Integer	Yes	Will be set if `event_type` is `comment`.
command String	Yes	If the integration type is a slash command we’ll include the command, e.g. `/hello`.
command_argument String	Yes	If the integration type is a slash command we’ll include the command argument, e.g. for `/hello world` it would be `world`.

POST Parameters when an uninstall happens

When a team uninstalls your integration, you can expect the following parameters. You can use this to clean up any state you may have on your end.

Name	Optional	Description
event_type String	No	Will be `uninstall`.
install_id Integer	No	The unique id of the installation.
workspace_id Integer	No	The workspace the installation belonged to.
user_id Integer	No	The id of the uninstaller.
user_name String	No	The full name of the uninstaller.

POST Parameters when a ping happens

For debugging purposes, you might get a ping payload. You should respond back with a JSON {"content": "pong"}.

Name	Optional	Description
event_type String	No	Will be `ping`.
user_id Integer	No	The id of the pinger.
user_name String	No	The full name of the pinger.

Adding content back

If your handler wishes to post a response back, use the following JSON response:

{"content": "42 is the answer to everything."}

Error handling

Non-200 responses will be retried 10 times in the span of 12 hours.

Configure URL

We redirect users to the configure URL when setting up the integration. The configured URL lets you connect the installation to your app and also includes an incoming webhook URL, which you can use as an easy way to manually post new threads into Twist as an integration.

You’ll get following GET parameters served to your configure URL:

GET Parameters

Name	Required	Description
install_id Integer	Yes	The unique id of the installation.
post_data_url String	Yes	A unique URL you can use to post content to Twist.
user_id Integer	Yes	The id of the installer.
user_name String	Yes	The full name of the installer.

To get back to the installation page, please use https://twist.com/integrations/installation/{install_id}.

How to post data from a channel integration

curl -X POST -H 'Content-type: application/json' \
    --data '{"content":"42?"}' \
    "https://hooks.twist.com/api/v3/integration_incoming/post_data?install_id=...&install_token=..."

Simply make a POST request to the post_data_url. In the POST include your data encoded in JSON.

POST Parameters

Name	Required	Description
content String	Yes	The content of the new object.
title String	No	Title of the new thread.

URL Reports

This feature provides a way to retrieve real content from an external source via GET request. When combined with the schedule feature may become a way to provide periodic information with real data.

Returning Markdown content

Automatic URL Reports can return plain Markdown content and Twist will use it as content for the new thread.

For example, the URL can return following (e.g. to generate automatic growth reports):

Apple today announced financial results for its fiscal 2017 second quarter ended April 1, 2017.

Core numbers:

* $78.4 Billion Revenue
* 78.3 Million iPhones
* 13.1 Million iPads Sold
* ...

Returning JSON content

The URL content can also return a JSON object specifying title and content of the new thread.

Content-type: application/json
{
    "title": "Webdev snippets | <date>",
    "content": "Please share your weeky snippets"
}

Note that you can use <date> in the title, and we will convert it to the current date.

Thread Updates

Thread Updates integration is installed on a thread level, and they can post new comments.

It provides an URL for distribution and installation, so the integration developer can provide it to his users. The installation page asks for write permission to one channel or thread and which teams it should notify.

Example usage: Post comments when new issues are added to a GitHub repository.

Incoming webhook

Sometimes a developer just want an incoming webhook URL to post via some script or external system without setting up a webserver and so on. It can be done via OAuth integration by using the token provided or via channel or thread integration.

To do that using a thread integration, you just have to create and install it. After the installation, Twist will provide the URL for manual posting.

Please follow the subsection on How to post data from a thread integration.

Outgoing webhook

Note: Outgoing webhook for threads is really different from the one provided by OAuth. 😉

Outgoing webhooks send data when an activity happens (e.g. a new comment is added to the thread or an uninstall happens).

It sends an HTTPS POST request to your specified URL and your webhook handler can respond to add data back to Twist. The payload depends on the integration type.

The outgoing hooks can work with any language or framework — as long as they support HTTPS and JSON.

POST Parameters when users add new objects

When a new message, thread or a new comment is added, you can expect following parameters.

Name	Optional	Description
event_type String	No	Can be `message`, `thread` or `comment` — depending where the slash command was used.
workspace_id Integer	No	The workspace the object was posted in.
content String	No	The content of object, e.g. thread or message content.
user_id Integer	No	The id of the poster.
user_name String	No	The name of the poster.
conversation_id Integer	Yes	Will be set if `event_type` is `message`.
conversation_title String	Yes	Will be set if `event_type` is `message`.
thread_id Integer	Yes	Will be set if `event_type` is `thread` or `comment`.
thread_title String	Yes	Will be set if `event_type` is `thread` or `comment`.
channel_id Integer	Yes	Will be set if `event_type` is `thread` or `comment`.
comment_id Integer	Yes	Will be set if `event_type` is `comment`.
command String	Yes	If the integration type is a slash command we’ll include the command, e.g. `/hello`.
command_argument String	Yes	If the integration type is a slash command we’ll include the command argument, e.g. for `/hello world` it would be `world`.

POST Parameters when an uninstall happens

When a team uninstalls your integration, you can expect following parameters. You can use this to clean up any state you may have on your end.

Name	Optional	Description
event_type String	No	Will be `uninstall`.
install_id Integer	No	The unique id of the installation.
workspace_id Integer	No	The workspace the installation belonged to.
user_id Integer	No	The id of the uninstaller.
user_name String	No	The full name of the uninstaller.

POST Parameters when a ping happens

For debugging purposes, you might get a ping payload. You should respond back with a JSON {"content": "pong"}.

Name	Optional	Description
event_type String	No	Will be `ping`.
user_id Integer	No	The id of the pinger.
user_name String	No	The full name of the pinger.

Adding content back

If your handler wishes to post a response back, use the following JSON response:

{"content": "42 is the answer to everything."}

Error handling

Non-200 responses will be retried 10 times in the span of 12 hours.

Configure URL

We redirect users to the configure URL when setting up the integration. The configured URL lets you connect the installation with your app and also includes an incoming webhook URL, which you can use as an easy way to post messages into Twist.

You’ll get following GET parameters served to your configure URL:

GET Parameters

Name	Required	Description
install_id Integer	Yes	The unique id of the installation.
post_data_url String	Yes	A unique URL you can use to post content to Twist.
user_id Integer	Yes	The id of the installer.
user_name String	Yes	The full name of the installer.

To get back to the installation page, please use https://twist.com/integrations/installation/{install_id}.

How to post data from a thread integration

curl -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:

Node.js.
ngrok | npm install ngrok -g.
A Twist account/workspace.

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

is_bot is now bot.
is_removed is now removed.

Threads

last_updated is deprecated.
is_starred is now starred.

Comment

is_deleted is now deleted.

Conversations

snippet_creator is deprecated.
message_count is deprecated.
name is deprecated.
is_private is now private.
A last_message object has been added which shows information about the last message, such as the creator, content, attachments and more.

Conversation Message

is_deleted is now deleted.