1. Home
  2. Help Articles
  3. API Documentation

API Documentation

Accessing Integrations

Workstorm offers your company the ability to connect to incoming webhooks to post messages to a Team conversation.

Your Company Admin can access the Workstorm webhook setup assistant by clicking on Settings in the top right of your Workstorm window and then Integrations under Organization Settings.

Setting Up a New Integration

Click on New Integration, enter a name, a description for your webhook and copy the API Token generated. Paste the API Token somewhere handy and click Activate Token to ensure the Token will work when the integration is finalized.

Double check that the toggle next to “Integration is enabled” is turned on before moving any further.

Next, search for the particular team you would like to deliver the automated message to. Copy the conversation ID for later use (see HTTP Post Instructions below) by clicking the provided button below the team name.

Click on the confirmation box to the left of the team name to confirm the chosen team conversation and then save your integration.

Deleting Integrations

If you would like to remove an enabled integration, click on Settings, Integrations, and then check the box to the left of the Integration you want to delete. Click the dropdown arrow within the Action box to the right of “Select All” and then choose “Delete.”

HTTP POST Request Instructions

To post a message to a conversation, send an HTTP POST request to https://app.workstorm.com/api/v1/post.

Request parameters can be passed as headers, query string params or in the request body as JSON-formatted document.

  • token (mandatory) – a secret sequence of characters used to authenticate the incoming webhook
  • conversation (mandatory) – the ID of a conversation to post the message to, which can be a team or a division. An Incoming Webhook must have an explicit permission in order to post to the conversation.
  • urgent (optional) – send as urgent, same as clicking on the SEND AS URGENT button in the message bar. Valid values are y, yes, true, n, no or false
  • text – the contents of a message to post.

Instead of passing message contents as a “text” field, you can set Content-Type header to text/plain and send the contents as the request body.

Examples

Posting a message with all parameters in JSON.

Posting an urgent message as text/plain body with parameters in headers and query string.

curl -H “Content-Type: text/plain” \

   -H “token: <token>” \

   {{baseURL}}/api/v1/post?’conversation=<conversation ID>&urgent=y’ \

   -d ‘message content’

curl {{baseURL}}/api/v1/post

   -d ‘{

     “token”: “<token>”,

     “conversation”: “<conversation ID>”,

     “text”: “Hello, world!”

   }’

Updated on January 8, 2020

Related Articles