Key concepts
Personal - an inbox belongs to one user. The API acts on the caller’s inboxes. Another user’s inbox returns404 with code INBOX_NOT_FOUND.
Teammate inboxes - admins and managers can act on a teammate’s inboxes with user_id: in the JSON body to create or update, as a query parameter to list or delete. The inbox is owned by the teammate and shows in the teammate’s switcher. Every source line must be accessible to the teammate. Without admin or manager rights, the request returns 403 with code FORBIDDEN.
With user_id, an admin or manager only reaches what sits in a workspace they manage. The list shows only the teammate’s inboxes with at least one source in such a workspace, and only those sources. An inbox outside it returns 404 on update or delete. Replacing sources keeps the teammate’s lines from other workspaces. Deleting an inbox that also holds lines from another workspace returns 403 with code FORBIDDEN. A teammate inbox must keep at least one line of the admin’s workspace, otherwise the request returns 400 with code INVALID_INBOX_SOURCE.
Sources - each source is an Allo line (allo_number) plus optional conditions. A source with an empty conditions list covers every conversation on the line. A MENU_BRANCH condition matches paths through the line’s phone menus. A MENU_OPTION condition matches keys of one menu.
Several options on one line - each line appears once in sources. To cover several menu options of the same line, put all their paths in the branches of a single MENU_BRANCH condition. Two sources with the same allo_number return 400 with code INVALID_INBOX_SOURCE.
Menu conditions need an engine-routed line - a menu condition is accepted only on a line whose menu options list is not empty, and only with paths from that list. On any other line, use a whole-line source with empty conditions.
Right after create - listing the conversations of an inbox created a moment ago can briefly return 404 with code INBOX_NOT_FOUND and retryable: true. Retry once. A 404 on update or delete is not retryable.
Suggestions first - Get inbox suggestions returns sources ranked from the caller’s recent calls and texts. Each suggestion carries a source to put in sources as is, so you never need menu node IDs. Use List menu options only to build a custom branch: each option carries a ready condition.
Listing conversations - pass inbox_id to List conversations instead of allo_number. The results hold conversations from several lines, each row with its own allo_number. The inbox’s sources and saved filters apply, but not the app’s Needs action and Mine tabs. “Unread only” is not saved on an inbox: pass the unread query parameter on List conversations.
Limits - up to 50 inboxes per user, 100 sources per inbox, 10 conditions per source, and 60 menu steps per inbox. A MENU_BRANCH takes 1 to 20 branches of 1 to 6 steps. Creating a 51st inbox returns 400 with code INBOX_LIMIT_REACHED. A name over 80 characters, an emoji over 16, or more than 100 sources or 10 conditions per source returns 400 with code INVALID_REQUEST_BODY, and field_errors names each field.
Scopes - reading needs INBOXES_READ, writing needs INBOXES_WRITE. A key without the scope gets 403 with code API_KEY_INSUFFICIENT_SCOPE.
Endpoints
List inboxes
Your inboxes, or a teammate’s
Get inbox suggestions
Ready-made sources ranked from recent activity
List menu options
The phone-menu options of a line, flattened
Create inbox
Create an inbox for yourself or a teammate
Update inbox
Rename, change sources or filters, mute or unmute
Delete inbox
Delete an inbox