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:

The HTTP error codes returned:

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:

And here are some common errors that you may encounter (you will find more info in error.error_message):

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.

Scopes

These are the scope permissions that the user grant your integration:

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:

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:

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:

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:

• Channels, both Outgoing and Incoming
• Threads, both Outgoing and Incoming

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.

When event_type is thread or channel, we'll also send these fields:

When event_type is message, we'll also send these fields:

Ping

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

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.

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.

Ping happens

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

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

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

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.

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.

Ping happens

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Return value

A workspace user object is returned.

Expected errors

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

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

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

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

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

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

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

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

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

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

Return value

A workspace user object is returned.

Expected errors

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Colors

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

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

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

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

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

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

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

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

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

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

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

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

Parameters

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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