Allo

Update inbox

Updates the fields sent and leaves the others unchanged. Use notifications muted to mute or unmute the inbox, and favorite to star or unstar it. Sending…

PATCH/v2/api/inboxes/{inbox_id}

Behavior

Updates only the fields you send and returns the inbox. Sending sources replaces the whole list. Sending filters replaces the saved filters, and "filters": null clears them. The app's Needs action and Mine settings on the inbox are kept either way. Sending "emoji": "" clears the emoji. An absent or null emoji keeps it.

To mute an inbox, send {"notifications_muted": true}. To unmute it, send false.

To star an inbox, send {"favorite": true}. Favorite inboxes show first in the app's inbox switcher, oldest star first, and the response carries favorited_at. Starring an inbox again keeps its first favorited_at. To unstar it, send false: favorited_at goes back to null.

Send user_id in the JSON body to update a teammate's inbox. Only admins and managers of the teammate's workspace can do that. An inbox with no source in a workspace the caller manages returns 404. Sending sources replaces only the lines in the caller's workspaces: the teammate's lines from other workspaces are kept.

Errors

StatusCodeWhen
400INBOX_NAME_REQUIREDname is sent 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
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
404INBOX_NOT_FOUNDNo inbox with this ID belongs to the inbox owner, or, with user_id, it has no source in a workspace the caller manages

Authorization

Authorizationstring · headerrequired

Api-Key ak_live_…

Path parameters

inbox_idstringrequired

Inbox ID (inb-*).

Body

namestring

Cannot be blank.

emojistring | null

"" clears the emoji. Absent or null keeps it.

sourcesobject[]

Replaces the whole list. With user_id, only the lines in the caller's workspaces are replaced.

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
favoriteboolean

true stars the inbox (starring it again keeps its first favorited_at), false unstars it. Absent keeps it.

user_idstring

Update this teammate's inbox (usr-*). The caller must be an admin or manager of that teammate's workspace.

Responses

200Inbox updated
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
404
429