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 |
---|---|---|
Send an IM message between bot and user |
||
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 |
Perform a slack action in a specified team as |
|
Team ID |
Get team_id from team_name |
|
User |
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