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.
Consider subscribing to the official mailing list to be notified about important communication about the API.
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 Authorization guide.
Temporary ids
Temporary ids are negative and can be used when adding, updating or deleting items.
Request, response, and error handling
The maximum allowed size of the request body for common requests is 5MB. Some attachments have their own limits for upload, please check their own sections for more details.
A response is always a JSON object which can be the following:
- On successful return: JSON data.
- On an error return, HTTP error code followed by:
{“error”: [error_code, error_string], **kwargs}
.
Dates
For dates we use ISO 8601. The formatting we can have inside the system:
- Date time:
%Y-%m-%d %H:%M:%S
. - Date only:
%Y-%m-%d
. - With timezone info:
%Y-%m-%d %H:%M:%S +00:00
.
The current API should only return %Y-%m-%d %H:%M:%S
, where the time zone is
implicit set to UTC
.
Errors
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 |
213 | The workspace has reached the maximum number of users. | 403 |
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
.
Authorization
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: Token exchange
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.
- General API Access - Authenticated clients (via OAuth) can access any of the API endpoints shown in the documentation here at their convenience.
- OAuth Webhooks - Authenticated webhooks that allow integrations to be notified on a variety of different Twist events.
- Bots - Interacts with users conversationally using a bot.
- Channel Updates - Has access to one channel and can post threads to it; these are done via REST webhooks.
- Thread Updates - Has access to one thread and can post comments to it; these are done via REST webhooks.
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_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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 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.
Note that using the @username notation within content
field of the bot reply to tag a specific recipient for the message is currently not supported.
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. |
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 |
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 . |
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 for channel integrations
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://api.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
- Plain text
JSON
If the remote endpoint response contains the Content-type: application/json
header, Twist will interpret the response as JSON. Two fields are supported:
title
- Twist will use this field for the title of the newly created thead.content
- Twist will use this field for the content of the newly created thead. The content field supports Markdown.
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 . |
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 . |
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 for thread integrations
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://api.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 be applied to Bots. 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 Examples
- OAuth. This will guide you through the steps required to authenticate your app with Twist to allow it access to a user's data. There are samples in both Python and Go.
Bot Examples
- Bot Integration. Responds with a simple message when the user talks to it. Available for Python, Node and Go.
- Long running bot. This will show you how to make use of the
url_callback
field so that your bot can respond to the initial request quickly, whilst still being able to perform a long running task before replying. There are samples for both Python and Go.
Webhooks Examples
- Channel Integration. Listens to GitHub and posts a new thread when a GitHub Issue is created. Available for Python, Node and Go.
General API Interaction Examples
- Action button. This will show you how to easily add action buttons into your messages and comments that gives the user a more dynamic way of interacting with your content. There are samples for both Python and Go.
- Attachments. This will show you how to add attachments to both conversation messages and thread comments, which is a two step process. There are samples in both Python and Go.
Batching requests
Example
$ curl -X POST https://api.twist.com/api/v3/batch \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-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",
"s60": "https://d10oy3rrrp8hu2.cloudfront.net/c5f14f4da3ee2479a26c65c630c21765_s60.jpg",
"s195": "https://d10oy3rrrp8hu2.cloudfront.net/c5f14f4da3ee2479a26c65c630c21765_s195.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": "0123456789abcdef0123456789abcdef01234567",
"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 avatar. Keys are image sizes (s35, s60, s195, s640), values are the urls. |
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 0123456789abcdef0123456789abcdef01234567"
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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-F image=@avatar.jpg
POST /api/v3/users/update_avatar
Updates the user's avatar. It currently supports the following formats:
- gif
- jpeg
- png
- bmp
- tiff
Note: the maximum allowed size for the avatar is 10MB
Parameters
Name | Required | Description |
---|---|---|
image String | Yes | Avatar image uploaded as multipart/form-data . |
Return value
The updated user object is returned.
Invalidate token
Example:
curl -X POST https://api.twist.com/api/v3/users/invalidate_token \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
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=0123456789abcdef0123456789abcdef01234567
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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
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 0123456789abcdef0123456789abcdef01234567" \
POST /api/v3/users/disconnect_google
Disconnects user's account from Google account.
Delete user
Example:
curl -X POST https://api.twist.com/api/v3/users/delete \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d password=userspw
POST /api/v3/users/delete
Delete the user. This deletes identifiable data such as full name and emails. This does not delete the user's content as the content is owned by the workspace.
Parameters
Name | Required | Description |
---|---|---|
password String | Yes | The user's password. |
Return value
A {"status": "ok"}
if the user is successfully deleted.
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,
"avatar_id": "c5f14f4da3ee2479a26c65c630c21765",
"avatar_urls": {
"s35": "https://d10oy3rrrp8hu2.cloudfront.net/c5f14f4da3ee2479a26c65c630c21765_s35.jpg",
"s60": "https://d10oy3rrrp8hu2.cloudfront.net/c5f14f4da3ee2479a26c65c630c21765_s60.jpg",
"s195": "https://d10oy3rrrp8hu2.cloudfront.net/c5f14f4da3ee2479a26c65c630c21765_s195.jpg",
"s640": "https://d10oy3rrrp8hu2.cloudfront.net/c5f14f4da3ee2479a26c65c630c21765_s640.jpg"
},
"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. |
avatar_id String | The workspace's avatar id (logo). |
avatar_urls Object | A list of urls representing the workspace's avatar. Keys are image sizes (s35, s60, s195, s640), values are the urls. |
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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567"
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 0123456789abcdef0123456789abcdef01234567"
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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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.
Update workspace avatar
Example:
curl -X POST https://api.twist.com/api/v3/workspaces/update_avatar \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-F image=@avatar.jpg
POST /api/v3/workspaces/update_avatar
Updates the workspace's avatar (logo). The following formats are supported:
- gif
- jpeg
- png
- bmp
- tiff
Note: the maximum allowed size for the avatar is 10MB.
Parameters
Name | Required | Description |
---|---|---|
image String | Yes | Avatar image uploaded as multipart/form-data . |
Return value
The updated workspace object is returned.
Remove workspace
Example:
curl -X POST https://api.twist.com/api/v3/workspaces/remove \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-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 public channels
Example:
curl --get https://api.twist.com/api/v3/workspaces/get_public_channels \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-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
},
]
Workspace users
A workspace user has fewer attributes than the currently logged-in user because it represents the public information other users can see.
Example workspace user object
{
"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 . |
Get workspace users
GET /api/v4/workspace_users/get
Returns a list of workspace user objects for the given workspace id.
Example:
curl -X GET https://api.twist.com/api/v4/workspace_users/get \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d id=5517
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the workspace. |
Get workspace users ids
GET /api/v4/workspace_users/get_ids
Returns a list of workspace user ids for the given workspace id.
Example:
curl -X GET https://api.twist.com/api/v4/workspace_users/get_ids \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d id=5517
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the workspace. |
Add user to workspace
Example:
curl -X POST https://api.twist.com/api/v4/workspace_users/add \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d id=5517 \
-d email=user2@example.com
POST /api/v4/workspace_users/add
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. E.g., ('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.
Expected errors
Error code | Error explanation | HTTP status code |
---|---|---|
213 | The workspace has reached the maximum number of users. | 403 |
Resend invite
Example:
curl -X POST https://api.twist.com/api/v4/workspace_users/resend_invite \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d id=5517 \
-d email=user2@example.com
POST /api/v4/workspace_users/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/v4/workspace_users/update \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d id=5517 \
-d email=user2@example.com \
-d user_type=USER
POST /api/v4/workspace_users/update
Updates a person in a workspace. Note that one of email
or user_id
arguments is required.
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 | Yes (or user_id ) |
The email of the user to be updated. |
user_id Integer | Yes (or email ) |
The id of the user to update. |
Return value
The updated workspace user object is returned.
Remove user from workspace
Example:
curl -X POST https://api.twist.com/api/v4/workspace_users/remove \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d id=5517 \
-d email=user2@example.com
POST /api/v4/workspace_users/remove
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 id
Example:
curl --get https://api.twist.com/api/v4/workspace_users/getone \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d id=5517 \
-d user_id=10073
GET /api/v4/workspace_users/getone
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 by email
Example:
curl --get https://api.twist.com/api/v4/workspace_users/get_by_email \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d id=5517 \
-d email=user2@example.com
GET /api/v4/workspace_users/get_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 info
Example:
curl --get https://api.twist.com/api/v4/workspace_users/get_info \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d id=5517 \
-d user_id=10073
GET /api/v4/workspace_users/get_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/v4/workspace_users/get_local_time \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d id=5517 \
-d user_id=10073
GET /api/v4/workspace_users/get_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. |
Workspace users (deprecated)
Workspace user object
Example workspace user object
{
"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"
}
A workspace user has fewer attributes than the currently logged-in user because it represents the public information other users can see.
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 . |
Get workspace users
GET /api/v3/workspaces/get_users
Returns a list of workspace user objects for the given workspace id.
Example:
curl -X GET https://api.twist.com/api/v3/workspaces/get_users \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d id=5517
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the workspace. |
Add user to workspace
Example:
curl -X POST https://api.twist.com/api/v3/workspaces/add_user \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-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.
Expected errors
Error code | Error explanation | HTTP status code |
---|---|---|
213 | The workspace has reached the maximum number of users. | 403 |
Resend invite
Example:
curl -X POST https://api.twist.com/api/v3/workspaces/resend_invite \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-d id=5517 \
-d email=user2@example.com \
-d user_type=USER
POST /api/v3/workspaces/update_user
Updates a person in a workspace. Note that one of email
or user_id
arguments is required.
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 | Yes (or user_id ) |
The email of the user to be updated. |
user_id Integer | Yes (or email ) |
The id of the user to update. |
Return value
The updated workspace user object is returned.
Remove user from workspace
Example:
curl -X POST https://api.twist.com/api/v3/workspaces/remove_user \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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. |
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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 to group
Example:
curl -X POST https://api.twist.com/api/v3/groups/add_user \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-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 to group
Example:
curl -X POST https://api.twist.com/api/v3/groups/add_users \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-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 from group
Example:
curl -X POST https://api.twist.com/api/v3/groups/remove_user \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-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 from group
Example:
curl -X POST https://api.twist.com/api/v3/groups/remove_users \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-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,
"use_default_recipients": true,
"default_groups": [],
"default_recipients": [],
"is_favorited": false,
"icon": 1
}
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. |
use_default_recipients Boolean | Whether the channel should use default recipients. |
default_groups List of Integers | An array of groups (e.g. default_groups: [10000, 10001] ) who should be notified by default. |
default_recipients List of Integers | An array of users (e.g. default_recipients: [10000, 10001] ) who should be notified by default. |
is_favorited Boolean | Whether the channel is favorited. |
icon Integer | The icon of the channel. See Icons |
Get channel
Example:
curl --get https://api.twist.com/api/v3/channels/getone \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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. Minimum length is 1 and maximum length is 80 Unicode code points. |
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. |
default_groups List of Integers | No | An array of groups (e.g. default_groups: [10000, 10001] ) who should be notified by default. |
default_recipients List of Integers | No | An array of users (e.g. default_recipients: [10000, 10001] ) who should be notified by default. |
is_favorited Boolean | No | Whether the channel is favorited. |
icon Integer | No | The icon of the channel. See Icons |
Return value
A channel object is returned.
Update channel
Example:
curl -X POST https://api.twist.com/api/v3/channels/update \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-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. Minimum length is 1 and maximum length is 80 Unicode code points. |
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. |
default_groups List of Integers | No | An array of groups (e.g. default_groups: [10000, 10001] ) who should be notified by default. |
default_recipients List of Integers | No | An array of users (e.g. default_recipients: [10000, 10001] ) who should be notified by default. |
is_favorited Boolean | No | Whether the channel is favorited. |
icon Integer | No | The icon of the channel. See Icons |
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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-d id=6984
POST /api/v3/channels/unarchive
Unarchives a channel.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the channel. |
Favorite channel
Example:
curl -X POST https://api.twist.com/api/v3/channels/favorite \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d id=6984
POST /api/v3/channels/favorite
Favorites a channel.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the channel. |
Unfavorite channel
Example:
curl -X POST https://api.twist.com/api/v3/channels/unfavorite \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d id=6984
POST /api/v3/channels/unfavorite
Ununfavorites 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 0123456789abcdef0123456789abcdef01234567" \
-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 to channel
Example:
curl -X POST https://api.twist.com/api/v3/channels/add_user \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-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 to channel
Example:
curl -X POST https://api.twist.com/api/v3/channels/add_users \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-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 from channel
Example:
curl -X POST https://api.twist.com/api/v3/channels/remove_user \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-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 from channel
Example:
curl -X POST https://api.twist.com/api/v3/channels/remove_users \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-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 |
Grey |
1 | #4A90E2 |
Blue |
2 | #03B3B2 |
Turquoise |
3 | #008299 |
Teal Blue |
4 | #82BA00 |
Green |
5 | #D24726 |
Red |
6 | #AC193D |
Berry Red |
7 | #DC4FAD |
Magenta |
8 | #3BD5FB |
Sky Blue |
9 | #74E8D3 |
Mint Green |
10 | #FFCC00 |
Yellow |
11 | #FB886E |
Salmon |
Icons
Channels provide a color ID which can be between 1
and 255
.
Threads
Threads keep your team’s conversations organized by specific topics.
Thread object:
{
"actions":[],
"attachments":[],
"channel_id":6984,
"comment_count":3,
"content":"Let's discuss the Twist API...",
"creator":10073,
"direct_group_mentions":[],
"direct_mentions":[],
"groups":[],
"id":32038,
"last_edited_ts":1494488709
"last_obj_index":2,
"last_updated_ts":1494500713,
"muted_until_ts":null,
"participants":[10073, 10076],
"pinned": true,
"pinned_ts": 1494488710,
"posted_ts":1494488709,
"reactions":{},
"recipients":[10076],
"snippet":"OK!",
"snippet_creator":10073,
"starred":false,
"system_message":null,
"title":"Thread1",
"workspace_id":5517,
"is_archived":false,
"in_inbox":false
}
Properties of thread object
Name | Description |
---|---|
actions List of Action buttons | Action buttons attached to the comment. |
attachments List of Attachments | Files attached to the comment. |
channel_id Integer | The id of the channel. |
comment_count Integer | The number of comments. |
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. |
creator Integer | The user that created the thread. |
direct_group_mentions List of Integers | The groups that are directly mentioned. |
direct_mentions List of Integers | The users that are directly mentioned. |
groups List of Integers | The groups that will be notified. |
id Integer | The id of the thread. |
last_edited_ts Integer | The Unix time when the thread was last edited or null if it hasn't. |
last_obj_index Integer | The last comment's index. A value of -1 means the whole thread is unread. |
last_updated_ts Integer | The Unix time when the thread was last updated. |
muted_until_ts Integer | The Unix time until when the thread is muted. |
participants List of Integers | The users that were at some point attached to the thread or one of its comments. |
pinned Boolean | The flag that is set to "true" when the thread is pinned. |
pinned_ts Integer or null | The Unix time when the thread was pinned. |
posted_ts Integer | The Unix time when the thread was created. |
reactions Object | Reactions to the thread, where keys are the reactions and values the users that had that reaction. |
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 |
snippet String | A part of the last comment. |
snippet_creator Integer | The user id of the last comment. |
starred Boolean | Whether the thread is starred. |
system_message String | A system message. |
title String | The title of the thread. |
workspace_id Integer | The id of the workspace. |
is_archived Boolean | The flag that is set to "true" when the thread is archived |
in_inbox Boolean | The flag that is set to "true" when the thread is in the inbox |
Get thread
Example:
curl --get https://api.twist.com/api/v3/threads/getone \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-d channel_id=6984
GET /api/v3/threads/get
Gets all threads in a channel.
Parameters
Name | Required | Description |
---|---|---|
as_ids Boolean | No | If enabled, only the ids of the threads are returned. |
channel_id Integer | Yes | The id of the channel. |
filter_by String | No | A filter can be one of attached_to_me or everyone . Default is everyone . |
limit Integer | No | Limits the number of threads returned (default is 20 , maximum is 500 ). |
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. |
before_id Integer | No | Limits threads to those with a lower than the specified id. |
after_id Integer | No | Limits threads to those with a higher than the specified id. |
workspace_id Integer | No | The id of the workspace. |
is_pinned Boolean | No | If enabled, only pinned threads are returned. |
is_starred Boolean | No | If enabled, only starred threads are returned. |
order_by String | No | The order of the threads returned. Either desc (default, descending) or asc (ascending). Order is applied based on the last_updated attribute, or the thread id if before_id or after_id are used. |
exclude_thread_ids List of Integers | No | The thread ids that should be excluded from the results. |
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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567")]
POST /api/v3/threads/add
Adds a new thread to a channel.
Parameters
Name | Required | Description |
---|---|---|
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. |
attachments List of Attachments | No | List of attachments to the new thread. It must follow the JSON format returned by attachment#upload. |
channel_id Integer | Yes | The id of the channel. |
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. |
direct_group_mentions List of Integers | No | The groups that are directly mentioned. |
direct_mentions List of Integers | No | The users that are directly mentioned. |
groups List of Integers | No | The groups that will be notified. |
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. |
send_as_integration Boolean | No | Displays the integration as the thread creator. |
temp_id Integer | No | The temporary id of the thread. |
title String | Yes | The title of the new thread. The minimum length is 1, and the maximum length is 300 Unicode code points. |
Return value
A thread object is returned.
Update thread
Example:
curl -X POST https://api.twist.com/api/v3/threads/update \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567")]
POST /api/v3/threads/update
Updates an existing thread.
Parameters
Name | Required | Description |
---|---|---|
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. |
attachments List of Attachments | No | List of attachments to the thread. It must follow the JSON format returned by attachment#upload. |
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. |
direct_group_mentions List of Integers | No | The groups that are directly mentioned. |
direct_mentions List of Integers | No | The users that are directly mentioned. |
id Integer | Yes | The id of the thread. |
title String | No | The title of the thread. Minimum length is 1 and maximum length is 300 Unicode code points. |
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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-d id=32038
POST /api/v3/threads/unstar
Unstars a thread.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the thread. |
Pin thread
Example:
curl -X POST https://api.twist.com/api/v3/threads/pin \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d id=32038
POST /api/v3/threads/pin
Pins a thread.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the thread. |
Unpin thread
Example:
curl -X POST https://api.twist.com/api/v3/threads/unpin \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d id=32038
POST /api/v3/threads/unpin
Unpins 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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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:
[
{
"channel_id": 85302,
"thread_id": 439203,
"obj_index": 1,
"direct_mention": false
}
]
Return value
A list of unread thread objects.
Mark thread as read
Example:
curl -X POST https://api.twist.com/api/v3/threads/mark_read \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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. A value of -1 marks the whole thread as unread. |
Mark thread as unread for others
Example:
curl -X POST https://api.twist.com/api/v3/threads/mark_unread_for_others \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d id=32038 \
-d obj_index=-1
POST /api/v3/threads/mark_unread_for_others
Marks the thread as being unread for others. Can be useful to notify others about thread changes.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the thread. |
obj_index Integer | Yes | The index of the last unread message. A value of -1 marks the whole thread as unread. |
Mark all threads as read
Example:
curl -X POST https://api.twist.com/api/v3/threads/mark_all_read \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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.
Close thread
Example:
curl -X POST https://api.twist.com/api/v3/comments/add \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d thread_id=32038 \
-d recipients=[10000, 10001] \
-d content="OK!"
-d thread_action="close"
POST /api/v3/comments/add
In order to close a thread, you can simply add a new comment to the thread, but include the thread_action
of close
as part of your comment's payload. See Add Comment for more details on adding a comment.
Reopen thread
Example:
curl -X POST https://api.twist.com/api/v3/comments/add \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d thread_id=32038 \
-d recipients=[10000, 10001] \
-d content="OK!"
-d thread_action="reopen"
POST /api/v3/comments/add
In order to close a thread, you can simply add a new comment to the thread, but include the thread_action
of reopen
as part of your comment's payload. See Add Comment for more details on adding a comment.
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":[],
"deleted": false,
"deleted_by": null,
"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. |
deleted Boolean | Whether the comment is deleted. |
deleted_by Integer | The user that deleted the comment (or null if not deleted). |
system_message System message | A system message. |
posted_ts Integer | The Unix time when the comment 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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 (default is 20 , maximum is 500 ). |
order_by String | No | The order of the comments returned. Either desc (default, descending) or asc (ascending). Order is applied based on the obj_index attribute. |
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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567")]
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. |
thread_action string | No | Can be close or reopen . |
Return value
A comment object is returned.
Update comment
Example:
curl -X POST https://api.twist.com/api/v3/comments/update \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567"])
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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 (default is 20 , maximum is 500 ). |
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. |
before_id Integer | No | Limits conversations to those with a lower than the specified id. |
after_id Integer | No | Limits conversations to those with a higher than the specified id. |
order_by String | No | The order of the conversations returned. Either desc (default, descending) or asc (ascending). Order is applied based on the last_active attribute, or the conversation id if before_id or after_id are used. |
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 0123456789abcdef0123456789abcdef01234567" \
-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 to conversation
Example:
curl -X POST https://api.twist.com/api/v3/conversations/add_user \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-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 to conversation
Example:
curl -X POST https://api.twist.com/api/v3/conversations/add_users \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-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 from conversation
Example:
curl --get https://api.twist.com/api/v3/conversations/remove_user \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-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 from conversation
Example:
curl --get https://api.twist.com/api/v3/conversations/remove_users \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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:
[
{
"obj_index": 1,
"direct_mention": false,
"conversation_id": 13037
}
]
Return value
A list of unread conversation objects.
Mark conversation as read
Example:
curl -X POST https://api.twist.com/api/v3/conversations/mark_read \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 (default is 20 , maximum is 500 ). |
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 messages returned. Either desc (default, descending) or asc (ascending). Order is applied based on the obj_index attribute. |
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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567")]
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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567")]
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 0123456789abcdef0123456789abcdef01234567" \
-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. Will be truncated to 140 characters. |
message String | No | Message to be added when using prefill_* and send_* actions. Will be truncated to 2048 characters. |
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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 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 0123456789abcdef0123456789abcdef01234567" \
-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 (default is 30 , maximum is 500 ). |
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. |
archive_filter String | No | Gives the ability to filter threads based on their is_archived flag. Can be all , archived , and active . By default it's active . |
order_by String | No | The order of the threads returned. Either desc (default, descending) or asc (ascending). Order is applied based on the last_updated attribute. |
exclude_thread_ids List of Integers | No | The thread ids that should be excluded from the results. |
Return value
A list of thread objects is returned.
Archive all
Example:
curl -X POST https://api.twist.com/api/v3/inbox/archive_all \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d workspace_id=32038
POST /api/v3/inbox/archive_all
Archives all threads in a workspace.
Parameters
Name | Required | Description |
---|---|---|
workspace_id Integer | Yes | The id of the workspace. |
older_than_ts Integer | No | Only archives threads that are the same or older than this timestamp. |
Archive thread
Example:
curl -X POST https://api.twist.com/api/v3/inbox/archive \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d id=32038
POST /api/v3/inbox/archive
Archives a thread.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the thread. |
Unarchive thread
Example:
curl -X POST https://api.twist.com/api/v3/inbox/unarchive \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d id=32038
POST /api/v3/inbox/unarchive
Unarchives a thread.
Parameters
Name | Required | Description |
---|---|---|
id Integer | Yes | The id of the thread. |
Mark all inbox threads as read
Example:
curl -X POST https://api.twist.com/api/v3/inbox/mark_all_read \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d workspace_id=6984
POST /api/v3/inbox/mark_all_read
Marks all inbox threads in the workspace as read.
Parameters
Name | Required | Description |
---|---|---|
workspace_id Integer | Yes | The id of the workspace. |
Get inbox count
Example:
curl --get https://api.twist.com/api/v3/inbox/get_count \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d workspace_id=5517
GET /api/v3/inbox/get_count
Gets inbox count in a workspace for the authenticated user.
Parameters
Name | Required | Description |
---|---|---|
workspace_id Integer | Yes | The id of the workspace. |
Return value:
{
"data": 5,
"version": 1621334415
}
Return value
A JSON object with data
and version
attributes. The version
indicates the
last update timestamp, this is useful when parallel fetching the inbox count. The data
includes the number of threads in the inbox.
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 \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d query=texts
GET /api/v3/search
Searches for keywords in all channels, threads, and conversations. The results are always sorted by last_updated
attribute in descending order.
Parameters
Name | Required | Description |
---|---|---|
workspace_id Integer | Yes | The workspace to search. |
query String | Yes | The full-text query to search for. |
limit Integer | No | Limits the number of conversations (default is 20, maximum is 100). |
cursor_mark String | No | Token used for pagination. This token is returned as next_cursor_mark on the return object. |
type String | No | Filter by object type. Can be threads , messages or all . Default is all . |
title String | No | Filter by thread or conversation title. |
from_user_id Integer | No | Filter by user id who created the object. |
to_user_id Integer | No | Filter by users who were notified (thread.recipients , comment.recipients or conversation.user_ids ). |
to_group_id Integer | No | Filter by groups who were notified (thread.groups , comment.groups ). |
conversation_ids JSON-encoded list of integers | No | Filter objects by conversation ids. |
channel_ids JSON-encoded list of integers | No | Filter objects by channel ids. |
before_ts Integer (Unix timestamp of the datetime) | No | Filter objects by creation date. |
after_ts Integer (Unix timestamp of the datetime) | No | Filter objects by creation date. |
Return object details
Name | Description |
---|---|
items List of Search Results | The search result of threads and conversations 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. Only set if has_more=true . |
is_plan_restricted Boolean | Free plans are restricted to view data older than 1 month. If true search has been limited and the clients should show an upgrade banner. For paying teams it will always be false. |
The items
Search Results:
Name | Description |
---|---|
id String | Unique id of the item. |
type String | The type of the match. Can be thread or conversation . |
title String | The title of the item. |
snippet String | Part of the text that matched the search query. |
snippet_creator_id Integer | The creator of the snippet. Can be null if the snippet is empty. |
snippet_last_updated_ts Integer | The Unix time when the snippet was last updated/posted. |
Thread specific attributes:
Name | Description |
---|---|
snippet_mask_poster String | Should the poster’s name be masked, e.g., this can be Github when Github posts things on behalf of the user. This is only returned for some threads. |
snippet_mask_avatar_url String | Should the poster’s avatar be masked, e.g., this can be Github avatar when Github posts things on behalf of the user. |
channel_id Integer | The channel id of the matching thread. |
thread_id Integer | The id of the matching thread. |
comment_id Integer | The id of the latest matching comment. It can be -1 if the query matches the thread title or content. |
closed Boolean | Indicates if the thread is closed. |
Conversation specific attributes:
Name | Description |
---|---|
conversation_id Integer | The id of the matching converation. This result is only returned when type=conversation . |
message_id Integer | The id of the latest matching message. |
user_ids List of integers | The users that are participating in the conversation. |
Search comments
Example:
curl --get https://api.twist.com/api/v3/search/thread \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d query=texts \
-d thread_id=401"
GET /api/v3/search/thread
Searches for keywords in a thread and returns the comment ids that match it. Maximally returns the latest 10.000 matches.
Parameters
Name | Required | Description |
---|---|---|
thread_id Integer | Yes | The id of the thread. |
query String | Yes | The full-text query to search for. |
from_user_id Integer | No | Filter by user id who created the object. |
to_user_id Integer | No | Filter by users who were notified (thread.recipients or comment.recipients ). |
to_group_id Integer | No | Filter by groups who were notified (thread.groups , comment.groups ). |
before_ts Integer (Unix timestamp of the datetime) | No | Filter objects by creation date. |
after_ts Integer (Unix timestamp of the datetime) | No | Filter objects by creation date. |
Return object details
Name | Description |
---|---|
comment_ids List of Integers | The ids of comments that match the query. These ids are always sorted by comment.id attribute in a ascending order. |
Search messages
Example:
curl --get https://api.twist.com/api/v3/search/conversation \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d query=texts \
-d conversation_id=42"
GET /api/v3/search/conversation
Searches for keywords in a conversation and returns the message ids that match it. Maximally returns the latest 10.000 matches.
Parameters
Name | Required | Description |
---|---|---|
conversation_id Integer | Yes | The id of the conversation. |
query String | Yes | The full-text query to search for. |
from_user_id Integer | No | Filter by user id who created the object. |
before_ts Integer (Unix timestamp of the datetime) | No | Filter objects by creation date. |
after_ts Integer (Unix timestamp of the datetime) | No | Filter objects by creation date. |
Return object details
Name | Description |
---|---|
message_ids List of Integers | The ids of messages that match the query. These ids are always sorted by message.id attribute in a ascending order. |
Autocomplete
This API allows you to provide autocomplete functionality for text-based searches. For example, you can use it to find threads that have strategy
in their title.
In the Twist clients, this API is used to implement the +
search that's used for Thread Referencing.
Query threads
Example:
curl --get https://api.twist.com/api/v3/autocomplete/query_threads \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d workspace_id=201 \
-d query=strategy
GET /api/v3/autocomplete/query_threads
Find threads matching some text in their title; this text can be anywhere inside the title. This will check all threads in all channels that the user has access to.
Parameters
Name | Required | Description |
---|---|---|
workspace_id Integer | Yes | The id of the workspace. |
query String | Yes | The text query to search for. |
limit Integer | No | Limits the number of threads returned. (default is 10 , maximum is 50 ). |
Return value
A JSON with [ ... thread objects ... ]
where thread objects
are a list of thread objects that match the query.
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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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. |
Get the URL join link
Example:
curl -X POST https://api.twist.com/api/v3/url_join/get_only \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-d workspace_id=5517
GET /api/v3/url_join/get_only
Gets a URL join link for the specified workspace.
Parameters
Name | Required | Description |
---|---|---|
workspace_id Integer | Yes | The id of the workspace. |
Return value
url
attribute can be null
if the URL join link isn't created or is disabled.
Return value:
{
"url": "https://twist.com/j/c5370f3ab4bad2d7eb6c432a17c37986"
}
Get or create URL join link
Example:
curl -X POST https://api.twist.com/api/v3/url_join/get_or_create \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-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"
}
Disable URL join link
Example:
curl https://api.twist.com/api/v3/url_join/disable \
-H "Authorization: Bearer 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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 String | 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 0123456789abcdef0123456789abcdef01234567" \
-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 0123456789abcdef0123456789abcdef01234567" \
-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
is_bot
is nowbot
.is_removed
is nowremoved
.
Threads
last_updated
is deprecated.is_starred
is nowstarred
.
Comment
is_deleted
is nowdeleted
.
Conversations
snippet_creator
is deprecated.message_count
is deprecated.name
is deprecated.is_private
is nowprivate
.- A
last_message
object has been added which shows information about the last message, such as thecreator
,content
,attachments
and more.
Conversation Message
is_deleted
is nowdeleted
.
Brand usage
Thanks for using Twist's APIs to build an integration!
If you plan to utilize Twist's logo or branding in the visual design of your integration or website, please adhere to Twist's brand guidelines.
In addition, please take note of the following:
- "Twist" should not be the first word in your integration's name. It may be used elsewhere in the name, though. For instance "x for Twist" or "x with Twist", etc. This makes it clear that your integration is created by you and not by Doist.
- You must clearly state that your integration is "not created by, affiliated with, or supported by Doist" in your integration description.
By using the Twist marks you agree to properly follow the above brand guidelines as well as our Terms of Service. For further information about the use of the Twist brand, please contact press@doist.com.
Market your app
Market your integration to Twist users with a custom integration page. Our searchable directory lets our audience easily find, install, and use your app — making it an effortless yet effective way to promote your work!
Get started today.
Submissions
To begin, fill out the app submissions form. Just add a marketing description, installation instructions, and links to your website and privacy policy.
If your integration is one that installs into Twist, we will also require an installation link for your integration. This can be found in the Installation
section of Twist App Console page
We'll also ask you for some images, in the following format:
- Your app icon, in JPG format on a white background. The size of the image should be 250x250px.
- One or more screenshots in JPG format at 1600x1000px. If your screenshot includes images of Twist it should use the light theme.
Review
After you've submitted your app, we'll email you a confirmation. We aim to review submissions and respond with any feedback within 10 business days.
During the review, we'll make sure:
- All the fields in the submission form are filled out in English.
- Your app complements or enhances the functionality of Twist. It should not replicate functionality already included.
- Your app is free of any functional errors during our testing.
- Your app integrates with Twist directly. We do not host listings for services that integrate solely via 3rd party automation providers like IFTTT or Zapier.
- Users can easily set up the integration using the instructions you've provided.
- All links provided are HTTPS enabled to ensure the security of our users. If you're submitting a native platform app, it needs to be signed with a trusted certificate.
- Any use of the Twist name or logo follow our brand guidelines.
- Your privacy policy ensures you will not sell or share our user's data to any third parties without their consent.
- The marketing descriptions and images you've provided are clear and follow our style.
If we find any issues along the way, we'll be in touch via email and work with you to resolve them. If you have any questions or updates at any time, you can reply to any of the emails you've received during the submissions process. We'll aim to get back to you within 2 business days.
Publishing
Once your submission has passed our review, we'll publish your listing and provide you with a public link that you can share! We'll also translate your listing to expand the reach of your marketing.
If you have any further questions or updates to provide after we've published your integration page, you can always reach out to our app submissions team at submissions@doist.com. We're happy to help!