Allo

Create inbox

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

StatusCodeWhen
400INBOX_NAME_REQUIREDname is missing or blank
400INVALID_INBOX_SOURCEA 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
400INVALID_REQUEST_BODYname over 80 characters, emoji over 16, more than 100 sources, or more than 10 conditions in a source. field_errors names each field
400INVALID_INBOX_FILTERSfilters has an unknown key or an invalid value
400INBOX_LIMIT_REACHEDThe inbox owner already has 50 inboxes
403FORBIDDENuser_id is set and the caller is not an admin or manager of that teammate's workspace
403ALLO_NUMBER_FORBIDDENA 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.

5 fields
typesenum<string>[]

INBOUND_CALLOUTBOUND_CALLTRANSFERREDINBOUND_TEXT_MESSAGEOUTBOUND_TEXT_MESSAGEVOICEMAILAI_ASSISTANT

user_idsstring[]

Teammates (usr-*), up to 50.

contact_idsstring[]

Contacts, up to 50.

contact_list_idsstring[]

Contact lists, up to 10.

tag_keysstring[]

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.

5 fields
typesenum<string>[]

INBOUND_CALLOUTBOUND_CALLTRANSFERREDINBOUND_TEXT_MESSAGEOUTBOUND_TEXT_MESSAGEVOICEMAILAI_ASSISTANT

user_idsstring[]

Teammates (usr-*), up to 50.

contact_idsstring[]

Contacts, up to 50.

contact_list_idsstring[]

Contact lists, up to 10.

tag_keysstring[]

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.

400
401
403
429