Skip to main content
Endpoint · GET /mailbox-categories
Endpoint somente de consulta: devolve informação e não modifica nada. Não é enviado dentro do array actions — é chamado diretamente.
Lista as caixas de entrada ativas do business em ordem alfabética, cada uma com sua categoria e o canal ao qual pertence. É o catálogo a partir do qual se descobre para qual caixa de entrada ou para qual categoria mover uma conversa com a ação assign_mailbox: o name devolvido por esta consulta é exatamente o valor que essa ação espera.
O path se chama mailbox-categories por herança, mas o que ele devolve são caixas de entrada, não categorias. A categoria de cada caixa de entrada vem no campo category de cada item.
A resposta é paginada por cursor opaco: enquanto has_more for true, repetir a chamada passando o next_cursor da página anterior em ?cursor=. Os cursores não são compartilhados entre endpoints diferentes, mesmo que o formato pareça igual. Parâmetros Todos os parâmetros de consulta são opcionais; sem nenhum deles é devolvida a primeira página do catálogo completo. O slug do business vai no path e é obrigatório.
  • search — substring do nome da caixa de entrada, sem diferenciar maiúsculas. O asterisco * funciona como curinga; % e _ são buscados literalmente.
  • category — devolve apenas as caixas de entrada desta categoria, por nome completo e sem diferenciar maiúsculas. Aceita * como curinga. As caixas de entrada sem categoria ficam excluídas, e uma categoria inexistente devolve uma página vazia, não um erro.
  • channel — devolve apenas as caixas de entrada deste canal, pela sua chave pública. Não é um filtro por padrão: a chave é comparada de forma exata contra sua forma canônica —sem diferenciar maiúsculas— e o * não atua como curinga. Uma chave inexistente, parcial ou com * devolve 404 CHANNEL_NOT_FOUND.
  • cursor — cursor opaco devolvido pela página anterior em next_cursor. Omitir para pedir a primeira página.
  • limit — caixas de entrada por página. Padrão 30, máximo 100.

​
Resposta

  • name — nome da caixa de entrada. É o que se passa como mailbox em assign_mailbox.
  • category — categoria à qual a caixa de entrada pertence, ou null se não tiver. Somente a caixa de entrada padrão de cada canal pode vir como null; a essas sempre se atribui por mailbox.
  • channel — chave pública do canal ao qual a caixa de entrada pertence. Uma caixa de entrada vive em um único canal, então este campo indica sobre quais conversas ela pode ser usada.
  • next_cursor — cursor da página seguinte; null quando has_more for false.
  • has_more — indica se há mais resultados depois desta página.
Erros

​
Exemplo

Esta chamada é uma leitura: não cria, não move nem modifica nenhuma conversa. Apenas traz o catálogo de caixas de entrada para saber qual name usar depois em uma ação.
Com o name de uma caixa de entrada desta resposta já é possível montar a ação Atribuir caixa de entrada, que é a que efetivamente move a conversa. Se, em vez da caixa de entrada exata, for passado o category dessa mesma resposta, a plataforma distribui a carga e escolhe a caixa de entrada menos carregada da categoria.