NAV Navbar

Introduction

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

Authentication

You can login via /api/v3/users/login and retrieve your user token. For public integration, you must use our OAuth 2 authentication.

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

Temporary ids

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

Request, response, and error handling

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

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

Dates

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

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

Errors

Example of error JSON object

{
    "error_uuid": "f699b0e0caa4446e847e17cc1d42801b",
    "error_code": 200,
    "error_extra": { },
    "error_string": "Invalid token"
}

Errors will be returned as JSON objects.

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.

Testing Purposes

For production uses, always go through the OAuth flow to get authentication tokens, however for testing purposes, you can take a shortcut and retrieve your personal token, which can be accessed from the OAuth section of your integration’s details page.

The test token is for the current logged in user and will have the full scope access.

Integrations

Twist has multiple types of integrations, and you have to pick your type based on how your integration will be used.

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

Accessing the API

Once a user has successfully authenticated your app/integration, you can then access user’s data in a secure way or setup webhooks. The general steps needed to authenticate are described in our OAuth2 section.

General access

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

If you have an app that utilizes the Twist data, you could be using any of the API calls detailed in this document.

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

Outgoing webhook

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

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

These are the supported events:

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

Subscribe to a hook

Example

curl https://api.twist.com/api/v3/hooks/subscribe \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d target_url=https://hooks.yourdomain.com/<unique_target_url> \
  -d event=workspace_user_added

To start listening to changes you have to subscribe to a hook. The following parameters are accepted in the subscribe request:

Name Required Description
target_url String Yes The URL we should call when an event happens.
event 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.

For every webhook request we send to your target_url, we expect a HTTP status 2xx in response. If we receive a non-2xx response, we will still try again 5 times before giving up.

Unsubscribe from a hook

Example

curl https://api.twist.com/api/v3/hooks/unsubscribe \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d target_url=https://hooks.yourdomain.com/<unique_target_url>

To stop listening to changes just unsubscribe your hook. The following parameters are accepted:

Name Required Description
target_url String Yes The URL we should unsubscribe.

On a successful unsubscribe, we return a 200 OK.

Webhooks

Webhooks allow you to interact with Twist data when changes occur, or when you wish to post to Twist from some other source. We currently have two different ways in which this can be achieved depending on your needs.

REST hooks

We have two places where these hooks fit in:

Incoming webhooks are essentially just a URL for you to send your data to and it will then appear in the channel/thread.

Outgoing webhooks, however, are URLs provided when the integration is installed, we will then send relevant channel/thread updates to that URL. When these POST calls are made, you can have return content sent back which Twist will then display to the user.

Please see the relevant references for each of these.

OAuth hooks

OAuth webhooks provide a way for 3rd parties to subscribe to changes as they happen, they do not need to be put in when the integration is installed, so these can be done at any point by the 3rd party.

These allow for a finer tuned experience as individual events can be subscribed to, unlike REST hooks which are specific to their area.

Please see the relevant references for what you can subscribe to and how to manage that subscription.

Bots

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 to the initial webhook call with 204 No Content and your integration can continue to work and respond at its convenience. url_callback is only valid for 30 minutes, please inspect url_ttl to ensure that it’s still valid.

Adding content back

JSON return

{
    "content": "πŸ“Ή [/whereby whereby_username](https://whereby.com/whereby_username)",
    "attachments": "[...]",
    "actions": "[...]"
}

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

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

Bots, and slash commands, can also add both attachments, and action buttons by including them as part of the json response. This applies to whether your integration responds immediately, or via the url_callback URL, and should be added to the json in the same manner as if you were posting a new message.

Error handling

Non-2xx responses will be retried 3 times in the span of 30 minutes.

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

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.

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 whereby.com integration, which lets you easily schedule video meetings (/whereby 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.

Thread

# formstring data

user_name: user_name
verify_token: 200_abcdefghijklmnopqrstuvwx
thread_id: 180000
workspace_id: 4800
command_argument: whereby_username
command: /whereby
thread_title: Test thread name
content: /whereby whereby_username
event_type: comment
comment_id: 6402000
channel_name: General
channel_id: 6000
user_id: 9000
url_callback: https://twist.com/....
url_ttl: 123456789

Conversation

# formstring data

user_id: 9000,
event_type: message,
conversation_title: conversation_title,
verify_token: 200_abcdefghijklmnopqrstuvwx,
content: /whereby username,
command: /whereby,
conversation_id: 296779,
command_argument: username,
user_name: John D.,
message_id: 3456789,
workspace_id: 1234,
url_callback: https://twist.com/....
url_ttl: 123456789

JSON return

{
    "content": "πŸ“Ή [/whereby whereby_username](https://whereby.com/whereby_username)",
    "attachments": "[...]",
    "actions": "[...]"
}

Outgoing webhook on slash command activity

Note: Outgoing webhook for slash commands is different from the one provided by OAuth. πŸ˜‰

We’ll send an outgoing webhook whenever your slash command is triggered (e.g., someone sends /gif cute cat).

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 to the initial webhook call with 204 No Content and your integration can continue to work and respond at its convenience. url_callback is only valid for 30 minutes, please inspect url_ttl to ensure that it’s still valid.

Adding content back

# JSON return
{
    "content": "πŸ“Ή [/whereby whereby_username](https://whereby.com/whereby_username)",
    "attachments": "[...]",
    "actions": "[...]",
    "options":{
      "add_new_message": true
    }
}

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

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

Slash commands, and bots, can also add both attachments, and action buttons by including them as part of the json response. This applies to whether your integration responds immediately, or via the url_callback URL, and should be added to the json in the same manner as if you were posting a new message.

Because slash commands are still regular messages in a conversation or thread, there may be occasions where you wish for the slash command’s response to either overwrite the original message, or post as a new message. By default, a slash command’s response (whether the response to the initial call, or via url_callback) will overwrite the original message, but if you do want a new message, provide the relevant option (add_new_message) in your JSON response.

Example implementation

You can check some code samples in the integration examples repository. Let’s use the python example implementation for the appear.in integration.

Your application will receive a POST call with message information in a formstring format, the integration can then decide what to do and it replies with JSON containing a content key. The text on this content key will replace the message containing the slash command.

Get all

Retrieves a full list of Slash commands for a team.

Example

curl https://api.twist.com/api/v3/slash_commands/get \
  -H "Authorization: Bearer 9b1bf97733c1ad5593cee12f3029079ddd3042cf" \
  -d workspace_id=1881

Return value:

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

POST Parameters

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

Return value

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

Channel Updates

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

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

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

Incoming webhook for channels

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

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

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

Outgoing webhook for channels

Note: Outgoing webhook for channels is really different from the one provided by OAuth. πŸ˜‰

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

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

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

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.

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.

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.

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.

Configure URL

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

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

GET Parameters

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

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

How to post data from a channel integration

CURL example

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

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

POST Parameters

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

URL Reports


// JSON: Sample URL Report Response

// Response header:
Content-type: application/json

// Response body:
{
    "title": "Webdev snippets | <date>",
    "content": "**Please** share your weeky snippets"
}



// Plain Text: Sample URL Report Response

**Please** share your weeky snippets

URL Reports are a way for integrations like Auto-reports to retrieve real content from an external source via a POST request and send it into Twist.

During the integration setup, the user provides a Content URL, which will be called based on the configuration of the integration (e.g., every week). The data the remote URL returns will then be posted into Twist.

When combined with the schedule feature, it can become a way to post updates from external sources into Twist automatically.

The URL endpoints the user defines can return two types of content:

JSON

If the remote endpoint response contains the Content-type: application/json header, Twist will interpret the response as JSON. Two fields are supported:

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

Plain Text

If the remote endpoint response doesn’t contain the Content-type: application/json header, Twist will interpret as plaintext content for a new thread. In this scenario, Markdown is also supported.

Thread Updates

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

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

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

Incoming webhook for threads

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

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

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

Outgoing webhook for threads

Note: Outgoing webhook for threads is really different from the one provided by OAuth. πŸ˜‰

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

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

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

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.

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.

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.

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.

Configure URL

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

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

GET Parameters

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

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

How to post data from a thread integration

CURL example

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

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

POST Parameters

Name Required Description
content String Yes The content of the new object.

Notes

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.

Timeouts

It’s important to be aware of the timeout restrictions on your integration. The restriction will apply to both Bots and Slash commands. Understanding the timeout restrictions can help you plan out your architecture strategy for your integration.

If your integration does not respond in under 10 seconds the server will drop the connection and try again as stated in the Error handling sections for each integration type.

Code Examples

To help you get started quickly integrating with Twist, we’ve written a few code samples that could come in handy.

If you’re missing a sample for the problem you’re trying to solve, ping us at integrations [at] doist.com and let’s talk! Alternatively, consider creating a pull request with the sample against our repo, we’re accepting contributions. :-)

Authentication

Bots

Webhooks

General API Interactions

Batching requests

Example

$ curl -X POST https://api.twist.com/api/v3/batch \
    -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
    -d requests='[{"method": "GET", "url": "https://api.twist.com/api/v3/workspaces/get?token=..."},
        {"method": "GET", "url": "https://api.twist.com/api/v3/workspaces/getone?token=...&id=201"}]'

POST /api/v3/batch

Batching allows you to pass several requests in a single HTTP request. Once all operations have been completed, a consolidated response will be passed back to you and the HTTP connection will be closed.

Return object

[
  {
    "code": 200,
    "headers": "...",
    "body": "..."
  },
  {
    "code": 200,
    "headers": "...",
    "body": "..."
  }
]

Parameters

Name Required Description
requests List of Objects Yes The requests to send.
requests[“method”] String Yes The HTTP method like GET or POST.
requests[“url”] String Yes The completed URL with any arguments needed.

Users

A user represents a real person who collaborates with other users.

User object:

{
  "scheduled_banners": [
    "notification_permissions"
  ],
  "short_name": "User",
  "contact_info": "",
  "bot": false,
  "profession": "",
  "snooze_dnd_start": null,
  "client_id": "9ea8c3de-349e-11e7-976e-06b24c4507db",
  "timezone": "UTC",
  "removed": false,
  "avatar_id": "c5f14f4da3ee2479a26c65c630c21765",
  "avatar_urls": {
    "s35": "https://d10oy3rrrp8hu2.cloudfront.net/c5f14f4da3ee2479a26c65c630c21765_s35.jpg",
    "s195": "https://d10oy3rrrp8hu2.cloudfront.net/c5f14f4da3ee2479a26c65c630c21765_s195.jpg",
    "s60": "https://d10oy3rrrp8hu2.cloudfront.net/c5f14f4da3ee2479a26c65c630c21765_s60.jpg",
    "s640": "https://d10oy3rrrp8hu2.cloudfront.net/c5f14f4da3ee2479a26c65c630c21765_s640.jpg"
  }
  "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.
avatar_urls Object A list of urls representing the user’s avatars. Keys are image sizes (s35, s160, s195, s640), values are the urls themselves.
id Integer The id of the user.
comet_channel String The comet channel.
lang String The user’s language.
away_mode Object Away mode sets the user as away until some future date.
away_mode#type String The reason of being in away mode may be parental, vacation, sickleave, or other.
away_mode#date_from String The start date of the away mode in a %Y-%m-%d format. The date_from parameter is inclusive. optional.
away_mode#date_to String The end date of the away mode in a %Y-%m-%d format. The date_to parameter is exclusive, which means the user will start receiving notifications on this date.
first_name String The user’s first name.
comet_server String The comet server.
name String The user’s full name.
off_days List of integers Sets the user’s off days (where they will get no notifications). It should be an array of integers representing ISO weekdays, e.g. 1 is Monday and 7 is Sunday. E.g. [6, 7].
restricted Boolean Whether the user is restricted.
default_workspace Integer The user’s default workspace.
token String The user’s API token.
snooze_dnd_end String Stop time of do-not-disturb snooze for notifications.
snoozed Boolean Whether notifications are snoozed.
email String The user’s email.
setup_pending Integer/Boolean Whether setup is pending.
snooze_until Integer Snooze notifications for the specified number of seconds.

Login

Example:

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

POST /api/v3/users/login

Logs in existing user.

Parameters

Name Required Description
email String Yes The user’s email.
password String Yes The user’s password.
set_session_cookie Boolean No By default, a session cookie is set for the user.

Return value

The user object.

Log out

Example:

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

POST /api/v3/users/logout

Logs out user, and resets the session.

Get current user

Example:

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

GET /api/v3/users/get_session_user

Gets the associated user for access token used in the request.

Return value

The User object is returned.

Update

Example:

curl -X POST https://api.twist.com/api/v3/users/update \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d name=User

POST /api/v3/users/update

Update the logged-in user’s details

Parameters

Name Required Description
name String No The user’s full name.
email String No The user’s email.
password String No The user’s password.
default_workspace Integer No The user’s default workspace.
profession String No The user’s profession.
contact_info String No The user’s contact info.
timezone String No The user’s timezone.
snooze_until Integer No Snooze notifications for the specified number of seconds.
snooze_dnd_start String No Start time of do-not-disturb snooze for notifications.
snooze_dnd_end String No Stop time of do-not-disturb snooze for notifications.
away_mode Object No Away mode sets the user as away until some future date.
away_mode#type String No The reason of being in away mode may be parental, vacation, sickleave, or other.
away_mode#date_from String No The start date of the away mode in a %Y-%m-%d format. The date_from parameter is inclusive. optional
away_mode#date_to String No The end date of the away mode in a %Y-%m-%d format. The date_to parameter is exclusive, which means the user will start receiving notifications on this date.
off_days List of integers No Sets the user’s off days (where they will get no notifications). It should be an array of integers representing ISO weekdays, e.g. 1 is Monday and 7 is Sunday. E.g. [6, 7]

Return value

The updated user object is returned.

Update password

Example:

curl -X POST https://api.twist.com/api/v3/users/update_password \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d new_password=newsecret

POST /api/v3/users/update_password

Updates the user’s password.

Parameters

Name Required Description
new_password String Yes The user’s new password.

Return value

The user object is returned.

Update avatar

Example:

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

POST /api/v3/users/update_avatar

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

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

Parameters

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

Return value

The updated user object is returned.

Invalidate token

Example:

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

POST /api/v3/users/invalidate_token

Invalidates API token and generates a new token for the user.

Return value

The user object is returned, which also includes the new token.

Validate token

Example:

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

POST /api/v3/users/validate_token

Validates the user token.

Set presence

Example:

curl -X POST https://api.twist.com/api/v3/users/heartbeat \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d workspace_id=5517 \
  -d platform=api

POST /api/v3/users/heartbeat

Marks user as active on workspace.

Parameters

Name Required Description
workspace_id Integer Yes The id of the workspace.
platform String Yes The platform can be one of mobile, desktop or api.

Reset presence

Example:

curl -X POST https://api.twist.com/api/v3/users/reset_presence \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d workspace_id=5517

POST /api/v3/users/reset_presence

Marks user as inactive on workspace.

Parameters

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

Reset password

Example:

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

POST /api/v3/users/reset_password

Sends an email to reset the user’s password.

Parameters

Name Required Description
email String Yes The user’s email.

Set password based on reset code

Example:

curl -X POST https://api.twist.com/api/v3/users/set_password \
  -d reset_code=12345abcef
  -d new_password=newsecret

POST /api/v3/users/set_password

Sets the user password based on a reset code.

Parameters

Name Required Description
reset_code String Yes The reset code sent via email.
new_password String Yes The user’s new password.

Return value

The updated user object is returned.

Check Google connection

Example:

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

GET /api/v3/users/is_connected_to_google

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

Return value:

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

Disconnect from Google

Example:

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

POST /api/v3/users/disconnect_google

Disconnects user’s account from Google account.

Workspaces

A workspace is a shared place between different users. In the Twist UI they are usually called teams.

Workspace object:

{
   "id": 5517,
   "name": "Workspace1",
   "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.
default_channel Integer The id of the default channel.
default_conversation Integer The id of the default conversation.
creator Integer The id of the user that created the workspace.
created_ts Integer The Unix time when the workspace was created.
plan String The type of payment plan, either free or unlimited.

Get workspace

Example:

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

GET /api/v3/workspaces/getone

Gets a single workspace object by id.

Parameters

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

Return value

A workspace object is returned.

Get default workspace

Example:

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

GET /api/v3/workspaces/get_default

Gets the user’s default workspace.

Return value

A workspace object is returned.

Get all workspaces

Example:

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

GET /api/v3/workspaces/get

Gets all the user’s workspaces.

Return value

A list of workspace objects is returned.

Add workspace

Example:

curl -X POST https://api.twist.com/api/v3/workspaces/add \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d name=Workspace1

POST /api/v3/workspaces/add

Creates a new workspace.

Parameters

Name Required Description
name String Yes The name of the new workspace.
temp_id Integer No The temporary id of the workspace.

Return value

A workspace object is returned.

Update workspace

Example:

curl -X POST https://api.twist.com/api/v3/workspaces/update \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d id=63109 \
  -d name="New Name"

POST /api/v3/workspaces/update

Updates an existing workspace.

Parameters

Name Required Description
id Integer Yes The id of the workspace.
name String No The name of the workspace.

Return value

The updated workspace object is returned.

Remove workspace

Example:

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

POST /api/v3/workspaces/remove

Removes a workspace and all its data (not recoverable).

Parameters

Name Required Description
id Integer Yes The id of the workspace.
current_password String Yes The user’s current password.

Get workspace users

GET /api/v3/workspaces/get_users

Returns a list of users for the given workspace id. A workspace user has fewer attributes than the currently logged-in user because it represents the public information other users can see.

Workspace user object:

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

Example workspace user response

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

Properties of workspace user object

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

Add user

Example:

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

POST /api/v3/workspaces/add_user

Adds a person to a workspace.

Parameters

Name Required Description
id Integer Yes The id of the workspace.
email String Yes The user’s email.
name String No The user’s name.
user_type String No The user type (‘USER’, ‘GUEST’, ‘ADMIN’)
channel_ids List of Integers No A list of the channels ids. Ex: '[100, 101, 102]'

Return value

A workspace user object is returned.

Resend invite

Example:

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

POST /api/v3/workspaces/resend_invite

Sends a new Workspace invitation to the selected user.

Parameters

Name Required Description
id Integer Yes The id of the workspace.
email String Yes The user’s email.
user_id Integer No The id of the user to invite. If available, it will be used instead of the user’s email.

Update user

Example:

curl -X POST https://api.twist.com/api/v3/workspaces/update_user \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d id=5517 \
  -d email=user2@example.com \
  -d user_type=USER

POST /api/v3/workspaces/update_user

Updates a person in a workspace.

Parameters

Name Required Description
id Integer Yes The id of the workspace.
user_type String Yes The user’s type one of USER, ADMIN or GUEST.
email String No The email of the user to be updated.
user_id Integer No The id of the user to update. If available, it will be used instead of the user’s email.

Return value

The updated workspace user object is returned.

Remove user

Example:

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

POST /api/v3/workspaces/remove_user

Removes a person from a workspace.

Parameters

Name Required Description
id Integer Yes The id of the workspace.
email String Yes The user’s email.
user_id Integer No The id of the user to remove. If available, it will be used instead of the user’s email.

Get user by email

Example:

curl --get https://api.twist.com/api/v3/workspaces/get_user_by_email \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d id=5517 \
  -d email=user2@example.com

GET /api/v3/workspaces/get_user_by_email

Gets a user by email.

Parameters

Name Required Description
id Integer Yes The id of the workspace.
email String Yes The user’s email.

Return value

A workspace user object is returned.

Get user by id

Example:

curl --get https://api.twist.com/api/v3/workspaces/get_user_by_id \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d id=5517 \
  -d user_id=10073

GET /api/v3/workspaces/get_user_by_id

Gets a user by id.

Parameters

Name Required Description
id Integer Yes The id of the workspace.
user_id Integer Yes The user’s id.

Return value

A workspace user object is returned.

Get user info

Example:

curl --get https://api.twist.com/api/v3/workspaces/get_user_info \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d id=5517 \
  -d user_id=10073

GET /api/v3/workspaces/get_user_info

Gets the user’s info in the context of the workspace.

Parameters

Name Required Description
id Integer Yes The id of the workspace.
user_id Integer Yes The user’s id.

Get local time of user

Example:

curl --get https://api.twist.com/api/v3/workspaces/get_user_local_time \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d id=5517 \
  -d user_id=10073

GET /api/v3/workspaces/get_user_local_time

Gets the user’s local time.

Return value:

"2017-05-10 07:55:40"

Parameters

Name Required Description
id Integer Yes The id of the workspace.
user_id Integer Yes The user’s id.

Get public channels

Example:

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

GET /api/v3/workspaces/get_public_channels

Gets the public channels of workspace.

Parameters

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

Return value:

[
  {
    "workspace_id": 32345,
    "user_ids": [
      153454
    ],
    "name": "Marketing",
    "creator": 124657,
    "created_ts": 1518534447,
    "description": "",
    "archived": false,
    "id": 10302,
    "public": true
  },
]

Groups

A group organizes team members together so that you can communicate with them more easily. By doing so, a Twist group can be set to be notified in a thread and all members of that group will get the thread update in their inbox.

Group object:

{
   "id": 498,
   "name": "Group1",
   "description": null,
   "user_ids": [],
   "workspace_id": 5517,
}

Properties of group object

Name Description
id Integer The id of the group.
name String The name of the group.
description String The description of the group.
user_ids List of Integers The users that are part of the group.
workspace_id Integer The id of the workspace.

Get group

Example:

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

GET /api/v3/groups/getone

Gets a single group object.

Parameters

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

Return value

A group object is returned.

Get all groups

Example:

curl --get https://api.twist.com/api/v3/groups/get \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \ 
  -d workspace_id=5517

GET /api/v3/groups/get

Gets all groups in a workspace.

Parameters

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

Return value

A list of group objects is returned.

Add group

Example:

curl -X POST https://api.twist.com/api/v3/groups/add \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \ 
  -d workspace_id=5571 \
  -d name=Group1 \
  -d user_ids='[10073]'

POST /api/v3/groups/add

Adds a new group to a workspace.

Parameters

Name Required Description
workspace_id Integer Yes The id of the workspace.
name String Yes The name of the new group.
user_ids List of Integers No The users that will comprise the group.

Return value

A group object is returned.

Update group

Example:

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

POST /api/v3/groups/update

Updates an existing group.

Parameters

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

Return value

The updated group object is returned.

Remove group

Example:

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

POST /api/v3/groups/remove

Removes a group.

Parameters

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

Add user

Example:

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

POST /api/v3/groups/add_user

Adds a person to a group.

Parameters

Name Required Description
id Integer Yes The id of the group.
user_id Integer Yes The user’s id.

Add users

Example:

curl -X POST https://api.twist.com/api/v3/groups/add_users \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \ 
  -d id=498 \
  -d user_ids='[10073,10076]'

POST /api/v3/groups/add_users

Adds several people to a group.

Parameters

Name Required Description
id Integer Yes The id of the group.
user_ids List of Integers Yes The ids of the users.

Remove user

Example:

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

POST /api/v3/groups/remove_user

Removes a person from a group.

Parameters

Name Required Description
id Integer Yes The id of the group.
user_id Integer Yes The user’s id.

Remove users

Example:

curl -X POST https://api.twist.com/api/v3/groups/remove_users \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \ 
  -d id=498 \
  -d user_ids='[10073,10076]'

POST /api/v3/groups/remove_users

Removes several people 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

Channels organize your team’s threads around broad topics like team, project, location, or area of interest. They make it easier for teams to browse and find the information they need.

Channel object:

{
     "id": 6984,
     "name": "Channel1",
     "description": "",
     "creator": 10073,
     "user_ids": [
            2601,
            10073,
            10076
     ],
     "color": 1,
     "public": true,
     "workspace_id": 5517,
     "archived": false,
     "created_ts": 1494323074,
}

Properties of channel object

Name Description
id Integer The id of the channel.
name String The name of the channel.
description String The description of the channel.
creator Integer The user that created the channel.
user_ids List of Integers The users that will participate in the channel.
color Integer The color of the channel. See Colors
public Boolean If enabled, the channel will be marked as public.
workspace_id Integer The id of the workspace.
archived Boolean Whether the channel is archived.
created_ts Integer The Unix time when the channel was created.

Get channel

Example:

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

GET /api/v3/channels/getone

Gets a single channel object by id.

Parameters

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

Return value

A channel object is returned.

Get all channels

Example:

curl --get https://api.twist.com/api/v3/channels/get \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d workspace_id=5517

GET /api/v3/channels/get

Gets all channels in a workspace.

Parameters

Name Required Description
workspace_id Integer Yes The id of the workspace.
archived Boolean No If enabled, only archived conversations are returned. By default this is disabled.

Return value

A list of channel objects is returned.

Add channel

Example:

curl -X POST https://api.twist.com/api/v3/channels/add \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d workspace_id=5517 \
  -d name=Channel1

POST /api/v3/channels/add

Adds a new channel.

Parameters

Name Required Description
workspace_id Integer Yes The id of the workspace.
name String Yes The name of the new channel.
temp_id Integer No The temporary id of the channel.
user_ids List of Integers No The users that will participate in the channel.
color Integer No The color of the channel. See Colors
public Boolean No If enabled, the channel will be marked as public. Defaults to false.
description String No The description of the channel.

Return value

A channel object is returned.

Update channel

Example:

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

POST /api/v3/channels/update

Updates an existing channel.

Parameters

Name Required Description
id Integer Yes The id of the channel.
name String Yes The name of the new channel.
color Integer No The color of the channel. See Colors
public Boolean No If enabled, the channel will be marked as public.
description String No The description of the channel.

Return value

The updated channel object is returned.

Archive channel

Example:

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

POST /api/v3/channels/archive

Archives a channel.

Parameters

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

Unarchive channel

Example:

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

POST /api/v3/channels/unarchive

Unarchives a channel.

Parameters

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

Remove channel

Example:

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

POST /api/v3/channels/remove

Removes a channel. This action requires the specified channel to have been archived first.

Parameters

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

Add user

Example:

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

POST /api/v3/channels/add_user

Adds a person to a channel.

Parameters

Name Required Description
id Integer Yes The id of the channel.
user_id Integer Yes The user’s id.

Add users

Example:

curl -X POST https://api.twist.com/api/v3/channels/add_users \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d id=6984 \
  -d user_ids='[10076]'

POST /api/v3/channels/add_users

Adds several people to a channel.

Parameters

Name Required Description
id Integer Yes The id of the channel.
user_ids List of Integers Yes The ids of the users.

Remove user

Example:

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

POST /api/v3/channels/remove_user

Removes a person from a channel.

Parameters

Name Required Description
id Integer Yes The id of the channel.
user_id Integer Yes The user’s id.

Remove users

Example:

curl -X POST https://api.twist.com/api/v3/channels/remove_users \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d id=6984 \
  -d user_ids='[10076]'

POST /api/v3/channels/remove_users

Removes several people 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.

Colors

Channels provide a color ID which relate to the following colors:

Id Hexadecimal Name
0 #606060 #606060 Grey
1 #4A90E2 #4A90E2 Blue
2 #03B3B2 #03B3B2 Turquoise
3 #008299 #008299 Teal Blue
4 #82BA00 #82BA00 Green
5 #D24726 #D24726 Red
6 #AC193D #AC193D Berry Red
7 #DC4FAD #DC4FAD Magenta
8 #3BD5FB #3BD5FB Sky Blue
9 #74E8D3 #74E8D3 Mint Green
10 #FFCC00 #FFCC00 Yellow
11 #FB886E #FB886E Salmon

Threads

Threads keep your team’s conversations organized by specific topics.

Thread object:

{
   "id":32038,
   "title":"Thread1",
   "content":"Let's discuss the Twist API...",
   "starred":false,
   "creator":10073,
   "channel_id":6984,
   "workspace_id":5517,
   "attachments":[],
   "actions":[],
   "recipients":[10076],
   "participants":[10073, 10076],
   "groups":[],
   "reactions":{},
   "direct_mentions":[],
   "direct_group_mentions":[],
   "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. Mentions can be used as [Name](twist-mention://user_id) for users or [Group name](twist-group-mention://group_id) for groups. Check limits for size restrictions for the content.
starred Boolean 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 An array of users (e.g. recipients: [10000, 10001]) who were notified in this thread or the string 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.
direct_mentions List of Integers The users that are directly mentioned.
direct_group_mentions List of Integers The groups that are directly mentioned.
comment_count Integer The number of comments.
last_obj_index Integer The last comment’s index.
snippet String A part of the last comment.
snippet_creator Integer The user id of the last comment.
last_updated_ts Integer The Unix time when the thread was last updated.
muted_until Integer The Unix time until when the thread is muted.
system_message String A system message.
posted_ts Integer The Unix time when the thread was created.
last_edited_ts Integer The Unix time when the thread was last edited or null if it hasn’t.

Get thread

Example:

curl --get https://api.twist.com/api/v3/threads/getone \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d id=32038

GET /api/v3/threads/getone

Gets a thread object by id.

Parameters

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

Return value

A thread object is returned.

Get all threads

Example:

curl --get https://api.twist.com/api/v3/threads/get \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d channel_id=6984

GET /api/v3/threads/get

Gets all threads in a channel.

Parameters

Name Required Description
channel_id Integer Yes The id of the channel.
workspace_id Integer No The id of the workspace.
filter_by String No A filter can be one of attached_to_me, everyone and is_starred.
newer_than_ts Integer No Limits threads to those newer when the specified Unix time.
older_than_ts Integer No Limits threads to those older when the specified Unix time.
limit Integer No Limits the number of threads returned.
as_ids Boolean No If enabled, only the ids of the threads are returned.

Return value

A list of thread objects is returned.

Add thread

Example:

curl -X POST https://api.twist.com/api/v3/threads/add \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d channel_id=6984 \
  -d recipients=[10000, 10001] \
  -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 recipients=EVERYONE \
  -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. Mentions can be used as [Name](twist-mention://user_id) for users or [Group name](twist-group-mention://group_id) for groups. Check limits for size restrictions for the content.
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.
direct_mentions List of Integers No The users that are directly mentioned.
direct_group_mentions List of Integers No The groups that are directly mentioned.
recipients List of Integers or String No An array of users (e.g. recipients: [10000, 10001]) that will be attached to the thread. It also accepts the string EVERYONE, which notifies everyone in the workspace. If not included, the value will default to user_ids of the target channel. If you specify [], no Twist users will be notified, and the thread creator will become the sole participant.
groups List of Integers No The groups that will be notified.
temp_id Integer No The temporary id of the thread.
send_as_integration Boolean No Displays the integration as the thread creator.

Return value

A thread object is returned.

Update thread

Example:

curl -X POST https://api.twist.com/api/v3/threads/update \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d id=32038 \
  -d title=Thread1



# Update a thread with an attachment using two requests
curl -X POST https://api.twist.com/api/v3/threads/add \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d channel_id=6984 \
  -d title=Thread1 \
  -d attachments=[$(curl -X POST https://api.twist.com/api/v3/attachments/upload -F attachment_id=$(uuidgen) -F file_name=@mytext.txt -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf")]

POST /api/v3/threads/update

Updates an existing thread.

Parameters

Name Required Description
id Integer Yes The id of the thread.
title String No The title of the thread.
content String No The content of the thread. Mentions can be used as [Name](twist-mention://user_id) for users or [Group name](twist-group-mention://group_id) for groups. Check limits for size restrictions for the content.
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.
direct_mentions List of Integers No The users that are directly mentioned.
direct_group_mentions List of Integers No The groups that are directly mentioned.

Return value

The updated thread object is returned.

Remove thread

Example:

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

POST /api/v3/threads/remove

Removes a thread.

Parameters

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

Star thread

Example:

curl -X POST https://api.twist.com/api/v3/threads/star \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d id=32038

POST /api/v3/threads/star

Stars a thread. More information on what starring a thread is for can be found in Twist Help

Parameters

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

Unstar thread

Example:

curl -X POST https://api.twist.com/api/v3/threads/unstar \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d id=32038

POST /api/v3/threads/unstar

Unstars a thread.

Parameters

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

Move thread

Example:

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

POST /api/v3/threads/move_to_channel

Moves the 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.

Parameters

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

Get unread threads

Example:

curl --get https://api.twist.com/api/v3/threads/get_unread \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d workspace_id=5517

GET /api/v3/threads/get_unread

Gets unread threads in a workspace for the authenticated user.

Parameters

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

Return value:

[
    [
        85302, // channel_id
        439203, // thread_id
        -1 // last_read_object_index
    ]
]

Return value

A list of unread thread objects, where each unread thread object is an array with three values: the channel id, the thread id and the index of the last unread comment.

Mark thread as read

Example:

curl -X POST https://api.twist.com/api/v3/threads/mark_read \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d id=32038 \
  -d obj_index=2

POST /api/v3/threads/mark_read

Marks the thread as being 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.

Mark thread as unread

Example:

curl -X POST https://api.twist.com/api/v3/threads/mark_unread \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d id=32038 \
  -d obj_index=2

POST /api/v3/threads/mark_unread

Marks the thread as being unread.

Parameters

Name Required Description
id Integer Yes The id of the thread.
obj_index Integer Yes The index of the last unread message.

Mark all threads as read

Example:

curl -X POST https://api.twist.com/api/v3/threads/mark_all_read \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d channel_id=6984

POST /api/v3/threads/mark_all_read

Marks all threads in the 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.

Clear unread threads

Example:

curl -X POST https://api.twist.com/api/v3/threads/clear_unread \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d workspace_id=5517

POST /api/v3/threads/clear_unread

Clears unread threads in workspace.

Parameters

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

Mute thread

Example:

curl -X POST https://api.twist.com/api/v3/threads/mute \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d id=13037 \
  -d minutes=30

POST /api/v3/threads/mute

Mutes a thread for a number of minutes. This means you will not get notified in your inbox when a thread has new comments left on it.

Parameters

Name Required Description
id Integer Yes The id of the thread.
minutes Integer Yes The number of minutes to mute the thread.

Return value

A thread object is returned.

Unmute thread

Example:

curl -X POST https://api.twist.com/api/v3/threads/unmute \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d id=13037

POST /api/v3/threads/unmute

Unmutes a thread. The user will start to see the notification indicator in their inbox again when new comments are left on a now unmuted 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 posted to a thread.

Comment object:

{
   "id": 206113,
   "content": "OK!",
   "creator": 10076,
   "thread_id": 32038,
   "channel_id": 6984,
   "workspace_id": 5517,
   "obj_index": 2,
   "attachments": [],
   "recipients": [
      10073
   ],
   "groups": [],
   "reactions": {
      "πŸ‘": [
         10076
      ]
   },
   "direct_mentions":[],
   "direct_group_mentions":[],
   "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 comment. Mentions can be used as [Name](twist-mention://user_id) for users or [Group name](twist-group-mention://group_id) for groups. Check limits for size restrictions for the content.
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.
obj_index Integer A sequential, 0-based index of a comment within a given thread. Its primary purpose is to check the consistency of first-party clients by ensuring that no comments within the sequence are missing.
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 An array of users (e.g. recipients: [10000, 10001]) to notify. It also accepts the strings EVERYONE or EVERYONE_IN_THREAD, which notifies everyone in the workspace or everyone mentioned in previous posts of this 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.
direct_mentions List of Integers The users that are directly mentioned.
direct_group_mentions List of Integers The groups that are directly mentioned.
is_deleted Integer Whether the thread is deleted.
system_message System message A system message.
posted_ts Integer The Unix time when the thread was created.
last_edited_ts Integer The Unix time when the comment was last edited or null if it hasn’t.

Get comment

Example:

curl --get https://api.twist.com/api/v3/comments/getone \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d id=206113

GET /api/v3/comments/getone

Gets a single comment object by id.

Parameters

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

Return value

A comment object is returned.

Get all comments

Example:

curl --get https://api.twist.com/api/v3/comments/get \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d thread_id=32038

GET /api/v3/comments/get

Gets all comments in a thread.

Parameters

Name Required Description
thread_id Integer Yes The id of the thread.
newer_than_ts String No Limit comments to those newer than the specified Unix timestamp.
older_than_ts String No Limit comments to those older than the specified Unix timestamp.
from_obj_index Integer No Limit comments starting at the specified object index.
to_obj_index String No Limit comments ending at the specified object index.
limit Integer No Limits the number of comments returned, by default 20.
order_by String No The order of the comments returned one of DESC or ASC.
as_ids Boolean No If enabled, only the ids of the comments are returned.

Return value

A list of comment objects is returned.

Add comment

Example:

curl -X POST https://api.twist.com/api/v3/comments/add \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d thread_id=32038 \
  -d recipients=[10000, 10001] \
  -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 recipients=EVERYONE_IN_THREAD \
  -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. Mentions can be used as [Name](twist-mention://user_id) for users or [Group name](twist-group-mention://group_id) for groups. Check limits for size restrictions for the content.
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.
direct_mentions List of Integers No The users that are directly mentioned.
direct_group_mentions List of Integers No The groups that are directly mentioned.
recipients List of Integers or String No An array of users (e.g. recipients: [10000, 10001]) to notify. It also accepts the strings EVERYONE or EVERYONE_IN_THREAD, which notifies everyone in the workspace or everyone mentioned in previous posts of this thread. If not provided, EVERYONE_IN_THREAD will be used.
groups List of Integers No The groups that will be notified.
temp_id Integer No The temporary id of the comment.
mark_thread_position Boolean No By default, the position of the thread is marked.
send_as_integration Boolean No Displays the integration as the comment creator.

Return value

A comment object is returned.

Update comment

Example:

curl -X POST https://api.twist.com/api/v3/comments/update \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d id=206113 \
  -d content="OK!"



# Update a comment with an attachment using two requests
curl -X POST https://api.twist.com/api/v3/comments/update \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d id=206113 \
  -d content="OK!" \
  -d attachments=[$(curl -X POST https://api.twist.com/api/v3/attachments/upload -F attachment_id=$(uuidgen) -F file_name=@mytext.txt -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf"])

POST /api/v3/comments/update

Updates an existing comment.

Parameters

Name Required Description
id Integer Yes The id of the comment.
content String No The content of the comment. Mentions can be used as [Name](twist-mention://user_id) for users or [Group name](twist-group-mention://group_id) for groups. Check limits for size restrictions for the content.
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.
direct_mentions List of Integers No The users that are directly mentioned.
direct_group_mentions List of Integers No The groups that are directly mentioned.

Return value

A comment object is returned.

Remove comment

Example:

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

POST /api/v3/comments/remove

Removes a comment. Comments can only be removed by the original comment poster, or by an admin (See Get Workspace Users for the different user types).

Parameters

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

Mark position

Example:

curl -X POST https://api.twist.com/api/v3/comments/mark_position \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d thread_id=32038 \
  -d comment_id=206113

POST /api/v3/comments/mark_position

Marks the position of a thread. Our clients always try to scroll to the position you’ve last seen; we also mark this with a blue line in the user interface. Clients need to send to the API the last comment/message the user reads in a thread/conversation. Currently, the official clients only do this when the user scrolls to the last message of a thread/conversation.

Parameters

Name Required Description
thread_id Integer Yes The id of the thread.
comment_id Integer Yes The id of the comment.

Conversations

A conversation is a direct message exchange between the authenticated user and one or more users.

Conversation object:

{
   "id": 13037,
   "title": null,
   "private": true,
   "creator": 10076,
   "last_message": {
      "reactions": {},
      "workspace_id": 1245,
      "creator": 133822,
      "deleted": false,
      "actions": [],
      "conversation_id": 321441,
      "last_edited_ts": null,
      "direct_mentions": [],
      "direct_group_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_ts": null,
   "archived": false,
   "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 Boolean Whether the conversation is private, ie. between 2 users only.
creator Integer The user that created the thread.
last_message Conversation Message A conversation message 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_ts Integer The Unix time until when the conversation is muted.
archived Boolean Whether the conversation is archived.
created_ts Integer The Unix time when the conversation was created.

Get conversation

Example:

curl --get https://api.twist.com/api/v3/conversations/getone \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d id=13037

GET /api/v3/conversations/getone

Gets a single conversation object.

Parameters

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

Return value

A conversation object is returned.

Get or create conversation

Example:

curl -X POST https://api.twist.com/api/v3/conversations/get_or_create \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d workspace_id=5517 \
  -d user_ids='[10073,10076]'

POST /api/v3/conversations/get_or_create

Gets or creates a conversation with one or more users.

Parameters

Name Required Description
workspace_id Integer Yes The id of the workspace.
user_ids List of Integers Yes The users that will participate in the conversation.

Return value

A conversation object is returned.

Get all conversations

Example:

curl --get https://api.twist.com/api/v3/conversations/get \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d workspace_id=5517

GET /api/v3/conversations/get

Gets all conversations of a user in a workspace.

Parameters

Name Required Description
workspace_id Integer Yes The id of the workspace.
limit Integer No Limits the number of conversations.
newer_than_ts Integer No Limits conversations to those newer when the specified Unix time.
older_than_ts Integer No Limits conversations to those older when the specified Unix time.
order_by String No The order of the comments returned one of DESC or ASC.
archived Boolean No If enabled, only archived conversations are returned. By default it’s disabled.

Return value

A list of conversation objects is returned.

Update conversation

Example:

curl -X POST https://api.twist.com/api/v3/conversations/update \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d id=13037 \
  -d title=Title1

POST /api/v3/conversations/update

Updates an existing conversation.

Parameters

Name Required Description
id Integer Yes The id of the conversation.
title String Yes The title of the conversation.
archived Boolean No If enabled, the conversation is marked as archived.

Return value

A conversation object is returned.

Add user

Example:

curl -X POST https://api.twist.com/api/v3/conversations/add_user \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d id=13037 \
  -d user_id=10076

POST /api/v3/conversations/add_user

Adds a person to a conversation.

Parameters

Name Required Description
id Integer Yes The id of the conversation.
user_id Integer Yes The user’s id.

Add users

Example:

curl -X POST https://api.twist.com/api/v3/conversations/add_users \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d id=13037 \
  -d user_ids='[10076]'

POST /api/v3/conversations/add_users

Adds several people 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.

Remove user

Example:

curl --get https://api.twist.com/api/v3/conversations/remove_user \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d id=13037 \
  -d user_id=10076

GET /api/v3/conversations/remove_user

Removes a person from a conversation.

Parameters

Name Required Description
id Integer Yes The id of the conversation.
user_id Integer Yes The user’s id.

Remove users

Example:

curl --get https://api.twist.com/api/v3/conversations/remove_users \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d id=13037 \
  -d user_ids='[10076]'

GET /api/v3/conversations/remove_users

Removes several people 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.

Archive conversation

Example:

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

POST /api/v3/conversations/archive

Archives a conversation.

Parameters

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

Unarchive conversation

Example:

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

POST /api/v3/conversations/unarchive

Unarchives a conversation.

Parameters

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

Get unread conversations

Example:

curl --get https://api.twist.com/api/v3/conversations/get_unread \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d id=5517

GET /api/v3/conversations/get_unread

Gets unread conversations.

Parameters

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

Return value:

[
    [
        13037,
        1
    ]
]

Return value

A list of unread conversation objects, where each unread conversation object is an array with two values: the conversation id and the index of the last unread message.

Mark conversation as read

Example:

curl -X POST https://api.twist.com/api/v3/conversations/mark_read \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d id=13037 \
  -d messsage_id=1

POST /api/v3/conversations/mark_read

Marks a conversation as read.

Parameters

Name Required Description
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.

Mark conversation as unread

Example:

curl -X POST https://api.twist.com/api/v3/conversations/mark_unread \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d id=13037 \
  -d messsage_id=1

POST /api/v3/conversations/mark_unread

Marks a conversation as unread.

Parameters

Name Required Description
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.

Mute conversation

Example:

curl -X POST https://api.twist.com/api/v3/conversations/mute \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d id=13037 \
  -d minutes=30

POST /api/v3/conversations/mute

Mutes a conversation for a number of minutes. This will mean the user receives no notifications from this conversation during that period.

Parameters

Name Required Description
id Integer Yes The id of the conversation.
minutes Integer Yes The number of minutes to mute the conversation.

Return value

A conversation object is returned.

Unmute conversation

Example:

curl -X POST https://api.twist.com/api/v3/conversations/unmute \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d id=13037

POST /api/v3/conversations/unmute

Unmutes a conversation.

Parameters

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

Return value

A conversation object is returned.

Conversation messages

A conversation message is a message between the authenticated user and one or more other users participating in a conversation.

Conversation message object:

{
   "id": 514069,
   "content": "Hi!",
   "creator": 10073,
   "conversation_id": 13037,
   "workspace_id": 5517,
   "obj_index": 0,
   "attachments": [],
   "actions": [],
   "reactions": {},
   "direct_mentions":[],
   "direct_group_mentions":[],
   "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. Mentions can be used as [Name](twist-mention://user_id) for users or [Group name](twist-group-mention://group_id) for groups. Check limits for size restrictions for the content.
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 A sequential, 0-based index of a message within a given conversation. Its primary purpose is to check the consistency of first-party clients by ensuring that no messages within the sequence are missing.
attachments List of Attachments Files attached to the message.
actions List of Action buttons Action buttons attached to the message.
reactions Object Reactions to the thread, where keys are the reactions and values the users that had that reaction.
direct_mentions List of Integers The users that are directly mentioned.
direct_group_mentions List of Integers The groups that are directly mentioned.
is_deleted Integer Whether the message is deleted.
system_message System message A system message.
posted_ts Integer The Unix time when the message was created.
last_edited_ts Integer The Unix time when the message was last edited or null if it hasn’t.

Get message

Example:

curl --get https://api.twist.com/api/v3/conversation_messages/getone \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d id=514069

GET /api/v3/conversation_messages/getone

Gets a single conversation message.

Parameters

Name Required Description
id Integer Yes The id of the conversation message.

Return value

A conversation message object is returned.

Get all messages

Example:

curl --get https://api.twist.com/api/v3/conversation_messages/get \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d conversation_id=13037

GET /api/v3/conversation_messages/get

Gets the messages from a conversation.

Parameters

Name Required Description
conversation_id Integer Yes The id of the conversation.
limit Integer No Limits the number of messages returned.
from_obj_index Integer No Limit messages starting at the specified object index.
to_obj_index String No Limit messages ending at the specified object index.
order_by String No The order of the conversations returned one of DESC or ASC.
as_ids Boolean No If enabled, only the ids of the messages are returned.

Return value

A list of conversation message objects is returned.

Add message to conversation

Example:

curl -X POST https://api.twist.com/api/v3/conversation_messages/add \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d conversation_id=13037 \
  -d content="Hello!"



# Create a message with an attachment using two requests
curl -X POST https://api.twist.com/api/v3/conversation_messages/add \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d conversation_id=13037 \
  -d content="Hello!" \
  -d attachments=[$(curl -X POST https://api.twist.com/api/v3/attachments/upload -F attachment_id=$(uuidgen) -F file_name=@mytext.txt -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf")]

POST /api/v3/conversation_messages/add

Adds a message to an existing conversation.

Parameters

Name Required Description
conversation_id Integer Yes The id of the conversation.
content String Yes The content of the new message. Mentions can be used as [Name](twist-mention://user_id) for users or [Group name](twist-group-mention://group_id) for groups. Check limits for size restrictions for the content.
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.
direct_mentions List of Integers No The users that are directly mentioned.
direct_group_mentions List of Integers No The groups that are directly mentioned.

Return value

A conversation message object is returned.

Update message in conversation

Example:

curl -X POST https://api.twist.com/api/v3/conversation_messages/update \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d conversation_id=13037 \
  -d content="Hello!"



# Update a message with an attachment using two requests
curl -X POST https://api.twist.com/api/v3/conversation_messages/update \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d id=130371 \
  -d content="Hello!" \
  -d attachments=[$(curl -X POST https://api.twist.com/api/v3/attachments/upload -F attachment_id=$(uuidgen) -F file_name=@mytext.txt -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf")]

POST /api/v3/conversation_messages/update

Updates a message in the conversation. Only messages sent by the authenticated user can be updated.

Parameters

Name Required Description
id Integer Yes The id of the message.
content String No The content of the message. Mentions can be used as [Name](twist-mention://user_id) for users or [Group name](twist-group-mention://group_id) for groups. Check limits for size restrictions for the content.
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.
direct_mentions List of Integers No The users that are directly mentioned.
direct_group_mentions List of Integers No The groups that are directly mentioned.

Return value

A conversation message object is returned.

Remove message from conversation

Example:

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

POST /api/v3/conversation_messages/remove

Removes a message from conversation. Only the original poster of the message can remove it.

Parameters

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

Action buttons

Action buttons are used inside other objects like threads, comments or messages. As it’s possible to have many action buttons inside the same object, they are represented as a list of action buttons in the actions key.

They are used to make it easy to execute an action for the message received. An example of usage would be adding text to the message box or a link to another page.

Action buttons objects:

{
    ...,

    "actions": [
        {
            "action": "open_url",
            "url": "https://www.google.com",
            "type": "action",
            "button_text": "Open Url Action Btn"
        },
        {
            "action": "prefill_message",
            "message": "This message is prefilled by an action button",
            "type": "action",
            "button_text": "Prefill Message Action Btn"
        },
        {
            "action": "send_reply",
            "message": "This reply was sent by an action button",
            "type": "action",
            "button_text": "Send Reply Action Btn"
        },
    ],

    ...
}

Properties of the action button object

Name Description
action String The action of the button. It can be open_url, prefill_message, or send_reply.
type String The type of the button, for now just action is available.
button_text String The text for the action button.
message String Message to be added when using prefill_* and send_*actions.
url String URL to redirect. It’s used for open_url types.

Get action buttons

Action buttons cannot be retrieved alone, they are part of other objects like threads, comments, and messages. To retrieve them, use the get methods from the object in which they were inserted.

Add an action button

Action buttons cannot be added alone, they are part of other objects like threads, comments, and messages. To add them, you have to use the add methods from the object in which they will be inserted into.

Parameters to add new action buttons

Name Required Description
action String Yes The action of the button. It can be open_url, prefill_message, or send_reply.
type String Yes The type of the button, for now just action is available.
button_text String Yes The text for the action button.
message String No Message to be added when using prefill_* and send_* actions.
url String No URL to redirect in case the action used requires it.

Attachments

Files can be attached to threads, comments, or conversation messages.

Note: The maximum allowed size for the attachment is 100MB

Example:

{
   "attachment_id": "c8f962d3-491b-4a43-92c2-43f7ac076408",
   "title": "image.png",
   "url": "https://xxx.cloudfront.net/xxx/as/image.png",
   "url_type": "image",
   "file_name": "image.png",
   "file_size": 21601,
   "underlying_type": "image/png",
   "image": "https://xxx.cloudfront.net/xxx/as/image.png",
   "image_height": 100,
   "image_width": 100,
   "upload_state": "uploaded"
}

Properties

Name Description
attachment_id String The id of the attachment.
title String The title of the attachment.
url String The URL where the file is located.
file_name String The file’s name.
file_size Integer The file’s size in bytes.
underlying_type String The file’s media or content type (MIME).
upload_state String Upload state is uploaded on success, or failed otherwise.
url_type String The type of the file, such as file or image.
image String If file is an image, the URL to the image file.
image_width Integer If file is an image, the width of the image.
image_height Integer If file is an image, the height of the image.
duration String If file is audio, the duration of the audio.

Upload an attachment

Example:

curl -X POST https://api.twist.com/api/v3/attachments/upload \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \ 
  -F attachment_id=c8f962d3-491b-4a43-92c2-43f7ac076408 \
  -F file_name=@image.png

POST /api/v3/attachments/upload

Uploads a file.

Parameters

Name Required Description
attachment_id String Yes A UUID that will be the id of the attachment.
file_name String Yes The name of the file to be uploaded.

Return value

An attachment object is returned.

Remove an attachment

Example:

curl -X POST https://api.twist.com/api/v3/attachments/upload \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \ 
  -d attachment_id=c8f962d3-491b-4a43-92c2-43f7ac076408 \
  -d comment_id=241432

POST /api/v3/attachments/remove

Removes attachment from thread, comment or conversation message.

Parameters

Name Required Description
attachment_id Integer Yes The id of the attachment.
thread_id Integer Yes, this or comment_id or message_id The id of the thread.
comment_id Integer Yes, this or thread_id or message_id The id of the comment.
message_id Integer Yes, this or thread_id or comment_id The id of the conversation message.

Reactions

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

Reaction object:

{
   "πŸ‘": [
      10076,
      10073
   ],
   "πŸ˜„": [
      10076
   ]
}

Properties of reaction object

The reaction object is either null or has one or more key-value pairs.

Name Description
key String The reaction added by one or more users.
value List of Integers The users that added that specific reaction.

Get reactions

Example:

curl -X POST https://api.twist.com/api/v3/reactions/get \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d comment_id=206113

POST /api/v3/reactions/get

Gets reactions of a thread, comment or conversation message.

Parameters

Name Required Description
thread_id Integer Yes, this or comment_id or message_id. The id of the thread.
comment_id Integer Yes, this or thread_id or message_id. The id of the comment.
message_id Integer Yes, this or thread_id or comment_id. The id of the conversation message.

Return value

A reaction object is returned.

Add a reaction

Example:

curl -X POST https://api.twist.com/api/v3/reactions/add \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d reaction="πŸ‘" \
  -d comment_id=206113

POST /api/v3/reactions/add

Adds a reaction to a thread, comment or conversation message.

Parameters

Name Required Description
reaction String Yes The reaction to add.
thread_id Integer Yes, this or comment_id or message_id. The id of the thread.
comment_id Integer Yes, this or thread_id or message_id. The id of the comment.
message_id Integer Yes, this or thread_id or comment_id. The id of the conversation message.

Remove a reaction

Example:

curl -X POST https://api.twist.com/api/v3/reactions/remove \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d reaction="πŸ‘" \
  -d comment_id=206113

POST /api/v3/reactions/remove

Removes a reaction from thread, comment or conversation message.

Parameters

Name Required Description
reaction String Yes The reaction to remove.
thread_id Integer Yes, this or comment_id or message_id. The id of the thread.
comment_id Integer Yes, this or thread_id or message_id. The id of the comment.
message_id Integer Yes, this or thread_id or comment_id. The id of the conversation message.

Inbox

Inbox object:

[
   {  
      "id": 38677,
      "reactions": [],
      "participants": [],
      "creator": 1234,
      "title": "Thread title",
      ... 
    },
   { 
      "id": 32038,
      "reactions": [],
      "participants": [],
      "creator": 1234,
      "title": "Thread title",
      ... 
    }
   ...
]

The inbox unifies the start page view on all platforms.

It is actually a list of thread objects. It doesn’t contain all threads, but the most recent threads ordered by date.

Get inbox

Example:

curl --get https://api.twist.com/api/v3/inbox/get \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \ 
  -d workspace_id=5517

GET /api/v3/inbox/get

Get the authenticated user’s inbox

Parameters

Name Required Description
workspace_id Integer Yes The id of the workspace.
limit Integer No Limits the number of threads returned, by default to 30.
newer_than_ts Integer No Limits threads to those newer when the specified Unix time.
older_than_ts Integer No Limits threads to those older when the specified Unix time.

Return value

A list of thread objects is returned.

Search

The search query allows for finding threads and conversations matching some text.

Search for query

Example:

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

GET /api/v3/search/query

Searches for a string. This query string will be checked in all channels, threads, and conversations.

Return object:

{
  "hits": 25,
  "has_more": true,
  "next_cursor_mark": "96e22dcb41564ab5802736b1d1e009d3",
  "items": [
    {
      "obj_type": "thread",
      "title": "Far far away",
      "snippet": "It is a paradisematic country, in which roasted parts of sentences fly into your mouth.",
      "details_link": "/api/v3/search/comments?query=texts&workspace_id=201&thread_id=401",
      "id": 501,
      "thread_id": 401,
      "channel_id": 301,
      "last_posted_ts": 1486726709,
      "last_author": 101,
      "participants": [ 101, 102, 103, 104 ],
      "archived": false
    },
    {
      "obj_type": "conversation",
      "title": "Chat",
      "snippet": "Even the all-powerful Pointing has no control about the blind texts...",
      "details_link": "/api/v3/search/messages?query=texts&workspace_id=201&aggregate_id=123-345-678-9",
      "id": 703,
      "conversation_id": 601,
      "last_author": 101,
      "chunk_start_ts": 1486727013,
      "chunk_end_ts": 1486727132,
      "last_posted_ts": 1486727120,
      "participants": [ 101, 105 ],
      "user_ids": [ 101, 105],
      "archived": false
    }
  ]
}

Parameters

Name Required Description
query String Yes The full text query to search for.
limit Integer No Limits the number of conversations.
cursor_mark String No Token for pagination.

Return object details

Name Description
hits Integer The number of results found.
has_more Boolean Whether there are more results that were not returned.
next_cursor_mark String The cursor mark to use in order to get more results.
items List of Objects The actual result items, threads or conversations found.
obj_type String The type of the item, a thread or a conversation.
title String The title of the item.
snippet String Part of the text that matched the search query.
details_link String A URL that can be used to get more details on the item.
id Integer The id of the comment or message.
thread_id Integer The id of the thread that the comment is part of.
conversation_id Integer The id of the conversation the message is part of.
last_posted_ts Integer The timestamp of the last post in the discussion.
last_author Integer The id of the last user that wrote in that discussion.
participants List of Integers The user ids that participate in that comment or message.
user_ids List of Integers The user ids that have joined that conversation.
archived Boolean Whether conversation or thread’s channel is archived.

Get more details about comments

Example:

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

GET /api/v3/search/comments

Here we get more details about a thread and its comments.

Return object:

{
  "terms": [
    "texts"
  ],
  "items": [
    {
      "type": "thread",
      "expanded": true,
      "obj": {
        "id": 501,
        "last_obj_index": 3,
        "title": "Far far away",
        "content": "Far far away, behind the word mountains, far from the countries Vokalia and Consonantia, there live the blind texts.",
        "snippet": "It is a paradisematic country, in which roasted parts of sentences fly into your mouth.",
        "channel_id": 301,
        "workspace_id": 201,
        "creator": 101,
        "snippet_creator": 101,
        "comment_count": 4,
        "posted": "2017-02-10 14:12:22",
        "posted_ts": 1486735942,
        "last_updated": "2017-02-10 14:14:36",
        "last_updated_ts": 1486736076,
        "is_starred": 0,
        "attached_to_everyone": false,
        "participants": [
          101, 102, 103, 104
        ],
        "recipients": [
          101, 102, 103, 104
        ],
        "groups": [],
        "reactions": {},
        "attachments": [],
      },
    },
    {
      "type": "comment_range",
      "idx_start": 0,
      "idx_end": 3,
      "expand_link": "/api/v3/search/expand_comment_range?idx_end=3&thread_id=401&workspace_id=201&idx_start=0",
      "top_expand_link": "/api/v3/search/expand_comment_range?idx_end=3&thread_id=401&workspace_id=201&idx_start=0&direction=top",
      "bottom_expand_link": "/api/v3/search/expand_comment_range?idx_end=3&thread_id=401&workspace_id=201&idx_start=0&direction=bottom"
    }
  ],
}

Expand comment range

Example:

curl --get https://api.twist.com/api/v3/search/expand_comment_range \
    -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
    -d idx_end=3 \
    -d thread_id=401 \
    -d workspace_id=201 \
    -d idx_start=0

GET /api/v3/search/expand_comment_range

The thread is expanded, so that more comments are returned. This would be used to see additional comments around the one returned by the search results, where you can see the originally returned message, and you want to see what is either before, or after, this item, to give additional context to the returned item.

Return object:

{
  "terms": [],
  "items": [
   {
     "type": "comment",
     "expanded": false,
     "obj": {
       "id": 164313,
       "obj_index": 0,
       "content": "Separated they live in Bookmarksgrove right at the coast of the Semantics, a large language ocean.",
       "thread_id": 401,
       "channel_id": 301,
       "workspace_id": 201,
       "creator": 102,
       "posted": "2017-02-10 14:12:38",
       "posted_ts": 1486735958,
       "system_message": null,
       "is_deleted": false,
       "attached_to_everyone": false,
       "groups": [],
       "recipients": [
         101, 102, 103, 104
       ],
       "reactions": {},
       "attachments": [],
     },
  },
   ...
  ]

Get more details about messages

Example:

curl --get https://api.twist.com/api/v3/search/messages \
    -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
    -d query=hello \
    -d workspace_id=201 \
    -d aggregate_id=123-345-678-9

GET /api/v3/search/messages

Here we get more details about a conversation and its messages. This would be used to see additional comments around the one returned by the search results, where you can see the originally returned message, and you want to see what is either before, or after, this item, to give additional context to the returned item.

Return object:

{
  "terms": [
    "texts"
  ],
  "items": [
    {
      "type": "conversation_message_range",
      "idx_start": 0,
      "idx_end": 5,
      "expand_link": "/api/v3/search/expand_conversation_message_range?conversation_id=601&idx_end=5&workspace_id=201&idx_start=0",
      "top_expand_link": "/api/v3/search/expand_conversation_message_range?conversation_id=601&idx_end=5&workspace_id=201&idx_start=0&direction=top",
      "bottom_expand_link": "/api/v3/search/expand_conversation_message_range?conversation_id=601&idx_end=5&workspace_id=201&idx_start=0&direction=bottom",
    },
    {
      "type": "conversation_message",
      "expanded": false,
      "obj": {
        "obj_index": 6,
        "content": "Pityful a rethoric question ran over her cheek, then she continued her way. On her way she met a copy",
        "id": 702,
        "conversation_id": 601,
        "workspace_id": 201,
        "creator": 105,
        "posted_ts": 1486544628,
        "reactions": {},
        "attachments": [],
        "actions": [],
        "system_message": null,
        "is_deleted": false,
      },
    },
    {
      "type": "conversation_message",
      "expanded": true,
      "obj": {
        "obj_index": 7,
        "content": "Even the all-powerful Pointing has no control about the blind texts it is an almost unorthographic life.",
        "id": 703,
        "conversation_id": 601,
        "workspace_id": 201,
        "creator": 101,
        "posted_ts": 1486545169,
        "reactions": {
          "πŸ‘": [
            105
          ]
        },
        "attachments": [],
        "actions": [],
        "system_message": null,
        "is_deleted": false,
      },
    },
    {
      "type": "conversation_message",
      "expanded": false,
      "obj": {
        "obj_index": 8,
        "content": "One day however a small line of blind text by the name of Lorem Ipsum decided to leave for the far World of Grammar.",
        "id": 704,
        "conversation_id": 601,
        "workspace_id": 201,
        "creator": 105,
        "posted_ts": 1486545334,
        "reactions": {
          "πŸ‘": [
            101
          ]
        },
        "attachments": [],
        "actions": [],
        "system_message": null,
        "is_deleted": false,
      },
    }
  ]
}

Expand conversation message range

Example:

curl --get https://api.twist.com/api/v3/search/expand_conversation_message_range \
    -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
    -d conversation_id=601 \
    -d idx_end=5 \
    -d workspace_id=201 \
    -d idx_start=0 \
    -d direction=top

GET /api/v3/search/expand_conversation_message_range

The conversation is expanded, that is more comments are returned.

Return object:

{
  "terms": [],
  "items": [
    {
      "type": "conversation_message",
      "obj": {
        "obj_index": 0,
        "content": "She packed her seven versalia, put her initial into the belt and made herself on the way.",
        "id": 701,
        "conversation_id": 601,
        "workspace_id": 201,
        "creator": 105,
        "posted_ts": 1458834794,
        "reactions": {},
        "attachments": [],
        "actions": [],
        "system_message": null,
        "is_deleted": false,
      },
    },
    ...
  ],
}

Notifications

The authenticated user’s last notifications.

Notification object:

{
   "notifications": [
      {
         "id": 1,
         "type_id": 1,
         "workspace_id": 5517,
         "channel_id": 6984,
         "thread_id": 32038,
         "comment_id": 206113,
         "by_user_id": 10076,
         "posted_ts": 1494489787,
      }
   ],
   "last_read": 0
}

Properties of notification object

Name Description
id Integer The id of the notification.
type_id Integer The notification type: 1 when added to a comment, 2 when added to a thread, 3 when added to a workspace, 4 when removed from a workspace, 5 when added to a channel, and 6 when removed from a channel.
workspace_id Integer The id of the workspace.
channel_id Integer The id of the channel.
thread_id Integer The id of the thread.
comment_id Integer The id of the comment.
by_user_id Integer The id of the user that triggered the notification (notified the receiving user).
posted_ts Integer The Unix time when the notification took place.
last_read Integer The id of the last read notification.

Get last notifications

Example:

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

GET /api/v3/notifications/get

Gets the last notifications of the authenticated user.

Parameters

Name Required Description
limit Integer No Limits the number of threads returned.

Return value

A list of notification objects is returned.

Mark notifications as read

Example:

curl -X POST https://twist.com/api/v3/notifications/mark_read \
    -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf"
    -d notification_id=1

POST /api/v3/notifications/mark_read

Marks everything after specified notification as read.

Parameters

Name Required Description
notification_id Integer Yes The last read notification id.

Reset notifications

Example:

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

POST /api/v3/notifications/reset

Resets all notifications read status.

Notifications settings

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

Notifications settings object:

{
   "desktop_added_to_ws": true,
   "desktop_comments": false,
   "desktop_conversations": true,
   "desktop_removed_from_ws": true,
   "desktop_threads": false,
   "email_added_to_ws": true,
   "email_aggregate": true,
   "email_comments": true,
   "email_conversations": true,
   "email_removed_from_ws": true,
   "email_threads": true,
   "push_added_to_ws": true,
   "push_comments": false,
   "push_conversations": true,
   "push_delay": 120,
   "push_removed_from_ws": true,
   "push_threads": false,
   "badge_conversations": true,
   "badge_threads": true,
}

Properties of notifications settings object

Name Description
desktop_conversations Boolean Desktop notifications for new messages on conversations.
desktop_comments Boolean Desktop notifications for new comments attached to user.
desktop_threads Boolean Desktop notifications for new threads attached to user.
desktop_added_to_ws Boolean Desktop notifications when added to workspaces.
desktop_removed_from_ws Boolean Desktop notifications when removed from workspaces.
email_conversations Boolean Email notifications for new messages on conversations.
email_comments Boolean Email notifications for new comments attached to user.
email_threads Boolean Email notifications for new threads attached to user.
email_added_to_ws Boolean Email notifications when added to workspaces.
email_removed_from_ws Boolean Email notifications when removed from workspaces.
email_aggregate Boolean Email notifications digest.
push_conversations Boolean Push notifications for new messages on conversations.
push_comments Boolean Push notifications for new comments attached to user.
push_delay Integer Number of seconds before sending a push notification.
push_threads Boolean Push notifications for new threads attached to user.
push_added_to_ws Boolean Push notifications when added to workspaces.
push_removed_from_ws Boolean Push notifications when removed from workspaces.
badge_threads Boolean Badge notifications on unread threads (iOS).
badge_conversations Boolean Badge notifications on unread conversations (iOS).

Get notification settings

Example:

curl --get https://api.twist.com/api/v3/notifications_settings/get \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \ 
  -d workspace_id=5517

GET /api/v3/notifications_settings/get

Gets the authenticated user’s current notification settings.

Parameters

Name Required Description
workspace_id Integer Yes The workspace id.

Return value

A notifications settings object is returned.

Update notifications settings

Example:

curl -X POST https://api.twist.com/api/v3/notifications_settings/update \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \ 
  -d workspace_id=5517 \
  -d setting=desktop_conversations \
  -d value=true

POST /api/v3/notifications_settings/update

Updates user notifications settings.

Parameters

Name Required Description
workspace_id Integer Yes The workspace id.
setting String Yes The name of the notifications setting to update, see above.
value Boolean Yes The value of the notifications setting to update.

Update many notifications settings

Example:

curl -X POST https://api.twist.com/api/v3/notifications_settings/update_many \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \ 
  -d workspace_id=5517
  -d mapping='{"desktop_conversations":true,"email_comments":false}'

POST /api/v3/notifications_settings/update_many

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 a user to join a workspace using a special URL invite link.

URL join object:

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

Properties of URL join object

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

Example:

curl -X POST https://api.twist.com/api/v3/url_join/get_or_create \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d workspace_id=5517

POST /api/v3/url_join/get_or_create

Gets or creates a URL join link for the specified workspace.

Parameters

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

Return value:

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

Example:

curl https://api.twist.com/api/v3/url_join/disable \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d workspace_id=5517

POST /api/v3/url_join/disable

Disables a URL join link for a workspace.

Parameters

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

Join workspace

Example:

curl https://api.twist.com/api/v3/url_join/join_workspace \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d url_invite_code="https://twist.com/j/c5370f3ab4bad2d7eb6c432a17c37986"

POST /api/v3/url_join/join_workspace

Joins a user to the invited workspace using the URL link.

Parameters

Name Required Description
url_invite_code Integer Yes The URL join link.

Return value

A workspace object is returned.

Loop in

This allows you to add threads to a channel, add comments to a thread, or messages to conversation by sending them to an email address.

Note: the maximum allowed size of the email is 25MB.

Loop in object:

{
   "email": "loop.thread.1269327.e1349ef52835x96@m.twist.com"
}

Properties of URL join object

Name Description
email String The email address to use to add threads/comments/messages.

Get or create a loop in email

Example:

curl -X POST https://api.twist.com/api/v3/loop_in/get_or_create \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d obj_type=THREAD \
  -d obj_id=32038

POST /api/v3/loop_in/get_or_create

Gets or creates a loop in email.

Parameters

Name Required Description
obj_type String Yes The type of the object, one of CHANNEL, THREAD or CONVERSATION.
obj_id Integer Yes The id of the object.

Return value:

{
   "email": "loop.thread.1269327.e1349ef52835x96@m.twist.com"
}

Disable loop in email

Example:

curl -X POST https://api.twist.com/api/v3/loop_in/disable \
  -H "Authorization: Bearer 9b1bf97783c1ad5593dee12f3019079dbd3042cf" \
  -d obj_type=THREAD \
  -d obj_id=32038

POST /api/v3/loop_in/disable

Disables a loop in email.

Parameters

Name Required Description
obj_type String Yes The type of the object, one of CHANNEL, THREAD or CONVERSATION.
obj_id Integer Yes The id of the object.

Limits

Here are the limits for our main text fields:

Field Limit
thread.content 15.000 characters
comment.content 15.000 characters
conversation_message.content 15.000 characters

PS. if you’re writting in a latin language (like EN, ES, PT, etc.), it’s possible that we can hold more letters due to encoding but the table above is the recommended and guaranteed number of characters.

System Messages

System messages are messages that are not sent by a user, but Twist informing users of some action that has taken place. These can appear in Threads and in Conversations, but are part of the comment and conversation message objects.

System message object

{
    "is_integration": null,
    "initiator": 2435,
    "initiator_name": "Jan",
    "channel_id": 1290,
    "type": "REFERENCE",
    "comment_id": 56288719,
    "initiator_id": 2435,
    "thread_id": 1409756,
    "user_id": null,
    "user_name": null,
    "title": null,
    "old_title": null,
    "new_title": null,
    "channel_name": "My Channel",
    "integration_name": null,
}

Properties of system message object

Name Description
is_integration Boolean Whether this message originated from an integration
initiator Integer The user id of the user who triggered the system message
initiator_name String The name of the user who triggered the system message
channel_id Integer The ID of the channel in which the thread getting this message was shown
type String The type of system message, this can be “REFERENCE”, “USER_MASK”, “THREAD_CLOSED”, “THREAD_REOPENED”, “USER_ADDED”, “USER_REMOVED”, “USER_NOT_FOUND”, “USER_LEFT”, “TITLE_CHANGED”, “TITLE_REMOVED”, “THREAD_TITLE_UPDATED”, “TITLE_SET” “THREAD_MOVED”, “INTEGRATION_INSTALLED”, “INTEGRATION_PAUSED”, “INTEGRATION_REACTIVATD”, “INTEGRATION_UNINSTALLED”
comment_id Integer The ID of the associated comment for this message
initiator_id Integer The user id of the user who caused the system message
thread_id Integer The ID of the thread in which this message was shown
user_id Integer The ID of the non-initiating user in the system message
user_name String The user name of the non-initiating user in the system message
title String The thread title
old_title String The old name of the thread
new_title String The new name of the thread
channel_name String The name of the channel a thread has moved to
integration_name String The name of the integration

Migrating from v2 to v3

This guide outlines the key differences between version 2 and 3 of the Twist API.

The new v3 Twist API is largely based on the v2 API. Most changes are simply done by changing the URL from /v2/ to /v3.

Below are the breaking changes made during the transition between v2 and v3.

User

Threads

Comment

Conversations

Conversation Message