API¶

Omnibot has a set of APIs that can be used to get information from slack, or to allow other services to act on behalf of a slack app for a specified workspace. See the API docs for more detailed information.

By default the API disallows access to all routes. Please see the Configuration docs for how to manage access control for the API.

API route documentation¶

Resource	Operation	Description
	POST /api/v1/slack/send_im/(team_name)/(bot_name)/(email)	Send an IM message between bot and user
	GET /api/v1/slack/get_ims/(team_name)/(bot_name)	Get a list of IMs for a bot within a team
Channel	GET /api/v1/slack/get_channel/(team_name)/(bot_name)/(channel_name)	Get a channel from a team, via the channel_name
SlackAction	POST /api/v2/slack/action/(team_name)/(bot_name)	Perform a slack action in a specified team as
Team ID	GET /api/v1/slack/get_team/(team_name)	Get team_id from team_name
User	GET /api/v1/slack/get_user/(team_name)/(bot_name)/(email)	Get a user from a team, via their email

GET /api/v1/slack/get_channel/(team_name)/(bot_name)/(channel_name)¶

Returns a channel object from slack, for the provided channel_name in the team_name using the specified bot_name.

Example request:

GET /api/v1/slack/get_channel/myteam/mybot/general HTTP/1.1

Example response:

 HTTP/1.1 200 OK
 Content-Type: application/json

 {
   "channel": {
     "id": "C4VQ6NUNN",
     "name": "general",
     "is_channel": true,
     "created": 1491515285,
     "creator": "U4WF56QGP",
     "is_archived": false,
     "is_general": true,
     "unlinked": 0,
     "name_normalized": "general",
     "is_shared": false,
     "is_org_shared": false,
     "is_member": false,
     "is_private": false,
     "is_mpim": false,
     "members": [
       "U4WF56QGP",
       "U6HQQ19EC",
       "U6J3LTKSQ",
       "U6J4EGP44",
       "U6JDF1JBU",
       "U6JEGTFDZ",
       "U6JERPMJ7",
       "U6JG691MJ",
       "U6JGEQ0J0",
       "U6SAVUK44",
       "U750C7B37",
       "U7DH0H802"
     ],
     "topic": {
       "value": "test123",
       "creator": "U6J3LTKSQ",
       "last_set": 1507156612
     },
     "purpose": {
       "value": "This channel is for team-wide communication.",
       "creator": "",
       "last_set": 0
     },
     "previous_names": [],
     "num_members": 9
   }
}

Parameters

team_name (str) – The team to search for this channel, as configured in omnibot.
bot_name (str) – The bot to use for the request, as configured in omnibot.
channel_name (str) – The name of the channel to get.

Request Headers

x-envoy-internal – Header that indicates whether or not this request is coming from an internal service or not. This is auto-set by envoy and doesn’t need to be explicitly set.

Response Headers

Content-Type – application/json

Status Codes

200 OK – success
404 Not Found – channel with specified channel_name could not be found in the specified team using the specified bot.

GET /api/v1/slack/get_user/(team_name)/(bot_name)/(email)¶

Returns basic user information, for the provided email in the team_name using the specified bot_name.

Example request:

GET /api/v1/slack/get_user/myteam/mybot/user@example.com HTTP/1.1

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{"email": "user@example.com", "name": "Test User", "team_id": "T123456",
 "user_id": "U123ABC"}

Parameters

team_name (str) – The team to search for this user, as configured in omnibot.
bot_name (str) – The bot to use for the request, as configured in omnibot.
email (str) – The email address of the user to get.

Request Headers

x-envoy-internal – Header that indicates whether or not this request is coming from an internal service or not. This is auto-set by envoy and doesn’t need to be explicitly set.

Response Headers

Content-Type – application/json

Status Codes

200 OK – success
404 Not Found – user with specified email could not be found using the specified bot.

GET /api/v1/slack/get_team/(team_name)¶

Get a team_id, from its team_name.

Example request:

GET /api/v1/slack/get_team/myteam HTTP/1.1

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{"team_id": "T123456"}

Parameters

team_name (str) – The team to search for this user, as configured in omnibot.

Request Headers

x-envoy-internal – Header that indicates whether or not this request is coming from an internal service or not. This is auto-set by envoy and doesn’t need to be explicitly set.

Response Headers

Content-Type – application/json

Status Codes

200 OK – success
404 Not Found – team is not configured

POST /api/v1/slack/send_im/(team_name)/(bot_name)/(email)¶

Sends a message as a bot user to an IM (direct message) channel between a team member and a bot user, for the provided team_name, bot_name, and email.

Example request:

GET /api/v1/slack/send_im/myteam/mybot/myemail@example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
     "channel": "DC1234567",
     "message": {
         "bot_id": "BC1234567",
         "subtype": "bot_message",
         "text": "HI!",
         "ts": "1538593287.000100",
         "type": "message",
         "username": "mybot"
     },
     "ok": true,
     "ts": "1538593287.000100"
 }

Parameters

team_name (str) – The team to search for the given bot, as configured in omnibot.
bot_name (str) – The bot sending the IM to the user, as configured in omnibot.
email (str) – The email address of user to send message to

Response Headers

Content-Type – application/json

Status Codes

200 OK – success
400 Bad Request – slack call returned a non-OK status
404 Not Found – team, bot, IM unable to be found, or user deleted from slack team

GET /api/v1/slack/get_ims/(team_name)/(bot_name)¶

Returns list of IMs (DMs with a bot), for the provided bot_name and team_name.

Example request:

GET /api/v1/slack/get_ims/myteam/mybot

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{"ims":
     [
         {
             "id": 'D1234567',
             "created": 1518129625,
             "is_im": true,
             "is_org_shared": true,
             "user": "U1234567"
             "is_user_deleted": false,
             "priority": 0.01234567
         }
     ]
 }

Parameters

team_name (str) – The team to search for this user, as configured in omnibot.
bot_name (str) – The bot to use for the request, as configured in omnibot.

POST /api/v2/slack/action/(team_name)/(bot_name)¶

Perform an action against slack, as the provided bot_name in the provided team_name.

Example request:

POST /api/v1/slack/action/myteam/mybot HTTP/1.1
Content-Type: application/json

{
  "action": "chat.postMessage",
  "kwargs": {
    "channel": "test-omnibot",
    "text": "@example see #general and use @here",
    "as_user": true,
    "omnibot_parse": {
      "text": ["channels", "users", "specials"]
    }
  }
}

Request JSON Object

action (string) – slack api action to perform. example: chat.postMessage
kwargs (dict) – keyword arguments you’d pass into the associated slack api action. example: “text”: “@example see #general and use @here”
omnibot_parse (dict) – The keyword argument you’d like omnibot to parse, with a list of things to parse. example: {“text”: [“channels”, “users”, “specials”]}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "channel": "C12345",
  "message": {
    "bot_id": "B456123",
    "subtype": "bot_message",
    "text": "<@UABC123|example> see <#C12345|general> and use <!here|here>",
    "ts": "1523557397.000335",
    "type": "message",
    "username": "mybot"
  },
  "ok": true,
  "ts": "1523557397.000335"
}

Parameters

team_name (str) – The team to perform this action against, as configured in omnibot.
bot_name (str) – The bot to use for the request, as configured in omnibot.

Request Headers

x-envoy-internal – Header that indicates whether or not this request is coming from an internal service or not. This is auto-set by envoy and doesn’t need to be explicitly set.

Response Headers

Content-Type – application/json

Status Codes

200 OK – success
400 Bad Request – slack call returned a non-OK status