API pública Beta

Encontre conversas que precisam de atenção

Filtre por awaitingReply, unread, unassigned, assigneeId, agentGroupId, snoozed, priority ou tagIds. Aguardando resposta ignora notas internas; não lidas é específico do colega autenticado. Sem responsável significa nenhum responsável individual, mesmo que uma equipe esteja atribuída. As tags correspondem a qualquer ID informado.

GET /api/v1/conversations?status=open&awaitingReply=true&compact=true&sort=waitingSince&direction=asc

Ordene por waitingSince, lastMessageAt, createdAt ou prioridade de negócio, com direção asc ou desc. Os IDs desempatam. Filtros omitidos mantêm compact=false e snoozed=any. Na REST, tagIds aceita IDs separados por vírgula; o MCP também aceita uma lista. waitingSince começa na primeira mensagem recebida depois da última resposta; mensagens de acompanhamento e notas internas não o reiniciam. Rode essa varredura da fila de espera de forma agendada, mesmo quando nenhum webhook chegar, para que conversas antigas voltem a aparecer.

Fique em dia sem reler a caixa de entrada

Use GET /api/v1/sync com conversations:read. O feed persistente inclui mudanças em conversas, tags, mensagens, propriedades de contatos, memórias e registros de exclusão. Cada payload também exige o próprio escopo de leitura: corpos de mensagens precisam de messages:read e memórias precisam de contact-memory:read. Credenciais restritas recebem apenas os canais permitidos.

1. Comece sem cursor, siga nextCursor até hasMore ser false e salve esse cursor.
2. Leia as listas atuais de conversas e contatos e todo o histórico de que precisar para o seu estado inicial.
3. Reproduza a partir do cursor salvo para capturar as mudanças ocorridas durante essa leitura. Processe cada página e depois salve nextCursor.

Elimine duplicatas pelo id do evento: a reprodução entrega pelo menos uma vez, então as ações seguintes precisam de proteção própria contra duplicatas. Uma requisição sem cursor cobre a última hora, não um retrato completo. Os eventos ficam guardados por 30 dias; HTTP 410 resync_required significa carregar o estado de novo. Carregue de novo também depois de ampliar escopos ou acesso a canais. Use limit até 100 e maxBodyChars até 10.000 (padrão 500). Defina compact=true para receber os campos textPreview/textTruncated das mensagens, limitados a 200 caracteres, em vez de body/bodyTruncated. Webhooks podem acordar um agente; o feed continua disponível sem assinaturas de webhook ou quando a entrega de webhooks está atrasada.

Registre verificações uma vez e compartilhe o resultado

Antes de repetir uma investigação, leia list_conversation_checks (GET /api/v1/conversations/{conversationId}/checks). Salve um resultado com record_conversation_check (PUT no mesmo caminho), informando key, result, checkedBy e uma reference opcional para o ID ou a URL do card. Por exemplo: key=product-version, result=Shopstar Go verified, checkedBy=Engineer, reference=card-X. O Sonny registra o actorId autenticado e o timestamp checkedAt. Reutilizar uma key substitui só aquela verificação; isto é o estado atual, não um histórico. Leituras precisam de conversations:read e gravações de conversations:write, ambos limitados ao canal da conversa. Essas chamadas não enviam resposta nem marcam o vendedor como respondido.

Atribua e atualize o trabalho em lotes

Descubra colegas e equipes ativos que podem receber atribuições com GET /api/v1/members and /teams (members:read). As respostas incluem disponibilidade e acesso efetivo aos canais, sem endereços de e-mail. Use conversations:write para alterar status, priority, assigneeId, agentGroupId, snoozedUntil, snoozedUntilReply, addTagIds ou removeTagIds.

POST /api/v1/conversations/batch
{
  "conversationIds": ["conversation_1", "conversation_2"],
  "updates": { "agentGroupId": "team_1", "assignment": "round_robin" }
}

O rodízio escolhe um membro disponível da equipe que tenha acesso ao canal da conversa. Sem nenhum membro elegível, uma atualização individual retorna 409 e um item do lote falha. Cada lote aceita até 100 IDs únicos e aplica uma alteração atômica por conversa. Confira cada resultado { id, ok, error? }; alguns itens podem falhar. Os lotes usam o limite atual por requisição, sem cobrança ponderada pela quantidade de itens.

Compartilhe o contexto do cliente com o Sonny AI

Liste, salve e remova memórias de contatos com contact-memory:read/write. Informe tanto contactId quanto um sourceId acessível; o contato precisa ter uma conversa nessa origem. Os fatos salvos usam a mesma validação, o mesmo tratamento de duplicatas e os mesmos limites do app e são registrados como memórias manuais.

Leia as definições de propriedades em /api/v1/properties e leia ou defina valores em /api/v1/contacts/{contactId}/properties. O MCP disponibiliza list_properties, get_contact_properties e set_contact_property. Eles exigem contacts:read/write e acesso a todos os canais. Defina exatamente um propertyId ou propertyName, com um valor de texto ou null para limpá-lo. Valores de texto, número, URL, data e seleção são validados de acordo com a definição do campo.

PUT /api/v1/contacts/contact_1/properties
{ "propertyName": "Plan", "value": "Pro" }

GET /api/v1/contacts?property[Plan]=Pro

Os filtros de propriedades correspondem a textos armazenados exatos; várias propriedades precisam corresponder todas. Valores enviados pela API são identificados como dados da API no Co-Pilot e na resposta automática. As regras existentes de cliente verificado e de origem continuam valendo. Valores comuns de campos internos preenchidos manualmente continuam fora desse contexto de IA.

Leia os mesmos relatórios que sua equipe

Com reporting:read, chame GET /api/v1/reporting/{kind}. Os tipos são overview, volume, response-times, agents, sources, tags, csat, ai, knowledge, leads e online-hours. Overview combina contagens, tempos de resposta e CSAT. Os filtros são period (1–365 dias, padrão 30), datas from/to em par (to é exclusivo), granularity (day/month), source, assigneeId e tagId. Source aceita all, all-chat, all-email, website:{id} ou email:{id}.

Os relatórios usam as consultas do painel e as verificações de acesso atuais. Knowledge usa as datas e os canais permitidos, independentemente da origem, do responsável ou da tag selecionados. Online-hours mede a presença dos colegas acessíveis no espaço de trabalho; as contagens de conversas continuam limitadas por canal. Os endpoints /csat existentes mantêm o próprio escopo csat:read e podem descrever um conjunto diferente.

Envie arquivos com respostas ou notas internas

Conceda attachments:write e envie um arquivo de até 25 MB para uma conversa. POST /api/v1/attachments recebe os campos multipart file e conversationId. A resposta contém um id e expiresAt. Passe até 10 attachmentIds para uma resposta ou nota em até uma hora. Cada envio fica vinculado ao seu usuário e à conversa e só pode ser usado uma vez. Envios não usados são limpos após expirarem.

POST /api/v1/conversations/conversation_1/reply
{ "attachmentIds": ["upload_1"] }

Respostas exigem messages:send; notas internas exigem messages:write e nunca chegam aos clientes. Mensagens só com anexos são suportadas. Respostas por e-mail incluem os arquivos dentro do limite de tamanho do e-mail e links de download para o restante; e-mails de chat offline incluem links dos arquivos. Os links enviados por e-mail continuam funcionando enquanto o anexo existir, para que os destinatários possam abri-los depois. Encaminhar o e-mail compartilha o acesso a esses arquivos. Confira emailDeliveryStatus para ver falhas de entrega.

Leituras de mensagens autorizadas incluem downloadUrl, downloadExpiresAt, aiStatus, aiDescription e aiExtractedText, além de videoTranscripts para vídeos com link (Loom, Vimeo e outros). Os links de download duram 15 minutos; leia a mensagem de novo para obter links novos. Novos envios pela API/MCP ficam em armazenamento privado. Anexos mais antigos continuam públicos e são marcados como access=legacy_public: a URL original deles não expira. Ler uma mensagem inicia a leitura das imagens dela quando o espaço de trabalho tem o Sonny AI. Leituras de imagens e transcrições de vídeos terminam pouco depois da chegada da mensagem: enquanto alguma ainda estiver em andamento, a resposta começa com readsInProgress, cujo nextStep indica a chamada exata a fazer. Passe waitSeconds (até 30) para esperar por elas em uma única requisição. Mensagens do widget e em tempo real exibidas aos clientes nunca incluem extrações nem transcrições.