Creates an inbox for the caller, or for a teammate with user id in the body. Every source line must be accessible to the inbox owner. Up to 50 inboxes per…
POST/v2/api/inboxes
Behavior
Creates an inbox owned by the caller and returns it with 201. Send user_id in the JSON body to create it for a teammate instead: the inbox is owned by the teammate and shows in the teammate's inbox switcher. Only admins and managers of the teammate's workspace can do that.
Every source line must be accessible to the inbox owner, with the same line access rules as the app. A source with an empty conditions list covers the whole line. Build sources from the source of inbox suggestions, or from the condition of menu options.
Menu conditions are only accepted on a line whose menu options list is not empty. On any other line, use a whole-line source.
Each line appears once in sources. To cover several menu options of one line, put all their paths in the branches of a single MENU_BRANCH condition.
Errors
Status
Code
When
400
INBOX_NAME_REQUIRED
name is missing or blank
400
INVALID_INBOX_SOURCE
A source, condition or digit is null or invalid, a menu path is not in that line's menu options, two sources share an allo_number, or a teammate inbox would have no line in the caller's workspace
400
INVALID_REQUEST_BODY
name over 80 characters, emoji over 16, more than 100 sources, or more than 10 conditions in a source. field_errors names each field
400
INVALID_INBOX_FILTERS
filters has an unknown key or an invalid value
400
INBOX_LIMIT_REACHED
The inbox owner already has 50 inboxes
403
FORBIDDEN
user_id is set and the caller is not an admin or manager of that teammate's workspace
403
ALLO_NUMBER_FORBIDDEN
A source line is not accessible to the inbox owner, or, with user_id, is not in a workspace the caller manages
Authorization
Authorizationstring · headerrequired
Api-Key ak_live_…
Body
namestringrequired
Required and non-blank.
emojistring | null
sourcesobject[]required
2 fields
allo_numberstringrequired
Allo line (E.164). Each line appears once in sources.
conditionsobject[]
Empty or absent means every conversation on the line.
filtersobject
Saved filters, with the same meaning as the conversation list filters in the app. "Unread only" is not saved on an inbox: use the unread query parameter of List conversations.
Call tag keys (AI or manual tags, from GET /v2/api/tags), up to 20. A conversation matches when any of its calls on the inbox's lines has one of these tags, not only the last call. Each key must be a tag of your workspace.
notifications_mutedboolean
user_idstring
Create the inbox for this teammate (usr-*). The caller must be an admin or manager of that teammate's workspace.
Responses
201Inbox created
dataobject
7 fields
idstringrequired
namestringrequired
emojistring | nullrequired
sourcesobject[]required
2 fields
allo_numberstringrequired
Allo line (E.164).
conditionsobject[]required
Empty means every conversation on the line.
filtersobjectrequired
Saved filters, with the same meaning as the conversation list filters in the app. "Unread only" is not saved on an inbox: use the unread query parameter of List conversations.
Call tag keys (AI or manual tags, from GET /v2/api/tags), up to 20. A conversation matches when any of its calls on the inbox's lines has one of these tags, not only the last call. Each key must be a tag of your workspace.
notifications_mutedbooleanrequired
favorited_atstring<date-time> | nullrequired
When the owner starred the inbox, null when it is not a favorite. Favorites show first in the app's inbox switcher, oldest star first.