API REST

Conversas

Os canais dos projetos, as threads, as reações, as mensagens diretas e os apps das Conversas.

  • Conversas (/chat, um canal por projeto, como no Slack): de quem trabalha no projeto (admin, PO/PM, QA e dev; o stakeholder não vê, 403). GET /chat (tracker:read) lista os canais da pessoa do token (os projetos ativos): unread e mentions somados e channels, cada um com project (id, slug, name), unread (mensagens novas na conversa principal), mentions (menções e respostas nas threads dela ainda não lidas), last_message_at e url. GET /projects/{prefixo, slug ou id}/chat (tracker:read) traz project, url, people (quem pode ser mencionado com @Nome: id, name e me, a pessoa do token; vem também com ?thread_id), unread (as não lidas da pessoa do token), last_read_at, has_more e messages, da conversa principal na ordem em que foram escritas (sem cursor, as últimas 50; ?before=<id> as anteriores, ?after=<id> as que chegaram depois, ?limit= até 200, ?mark_read=1 marca como lida até a última devolvida). Com ?thread_id=<id> (a primeira mensagem de uma thread) traz thread (essa mensagem) e replies (as respostas, até 500; ?after=<id> só as novas; ?mark_read=1 marca as menções e respostas da thread como lidas). Cada mensagem: id, thread_id (a thread em que é resposta, ou null), in_channel e thread_root (author, text: a resposta da thread que também foi para a conversa principal e o começo da mensagem que ela responde), author, app (a mensagem escrita por um app, com key e name; null na de uma pessoa), author_id, author_avatar_url (a foto, null sem foto), text (markdown; vazio na excluída), at, edited_at, deleted (by, at), mine (escrita pela pessoa do token), can_edit e can_delete (o que ela pode fazer com a mensagem), mentions, mentions_me, issues (as tarefas citadas pelo código que a pessoa vê: code, title, open, url), reactions (emoji, count, mine, people), thread (na conversa principal: replies, last_reply_at e people, quem respondeu; null sem respostas) e url. POST /projects/{ref}/chat (tracker:write) envia {"text": "..."} na conversa principal ou {"text": "...", "thread_id": "<id>"} na thread daquela mensagem (com o id de uma resposta, entra na mesma thread; "also_in_channel": true também põe a resposta na conversa principal, como o "Também enviar para o canal" da tela; reply_to_id é o nome antigo; até 10.000 caracteres; @Nome menciona alguém do canal, e quem está na thread recebe a resposta, na Caixa de entrada, no sino e no aparelho) e devolve message (id, thread_id, url), 201. POST /projects/{ref}/chat/{id}/reactions (tracker:write) com {"emoji": "👍"} marca a reação da pessoa do token e DELETE com o mesmo corpo tira (cada pessoa, cada emoji uma vez; até 20 emojis diferentes por mensagem); devolve id, emoji e reacted. PATCH /projects/{ref}/chat/{id} (tracker:write, só quem escreveu) corrige com {"text": "..."}; DELETE /projects/{ref}/chat/{id} (tracker:write, quem escreveu ou admin) exclui (fica no lugar como excluída; o texto de antes vai para o histórico da empresa). POST /projects/{ref}/chat/read (tracker:read) com {"message_id": "<id>"} (ou {}, até agora) marca a conversa principal como lida e devolve unread. GET /projects/{ref}/chat/issues?q= (tracker:read) traz issues, as tarefas para citar numa mensagem, como a lista que abre ao escrever # no campo da tela (até 8; só as que a pessoa do token vê): sem q, pelo contexto, primeiro as citadas por último na conversa (reason cited), depois as abertas com a pessoa do token (mine) e as abertas do projeto mexidas por último (project); com o começo de um código (MOB- ou MOB-12, que acha MOB-0012), completa pelo código, primeiro as do projeto; com palavras, a busca por texto e sentido do /search (reason null). Cada uma: id, code, title, open, project (o nome), reason e url; o code escrito no text vira link e cartão. Projeto arquivado: só leitura (422 ao escrever). No MCP: list_chat_channels, list_chat_messages, send_chat_message, react_to_chat_message, edit_chat_message, delete_chat_message e suggest_chat_issues.
  • Mensagens diretas (/chat/direct/<id da pessoa>): a conversa particular entre a pessoa do token e outra pessoa da equipe da mesma empresa (quem trabalha em algum projeto dela, menos o stakeholder, e os admins e donos). Só as duas leem; nem o admin vê. GET /chat também traz directs (as conversas com mensagem, a mais recente primeiro: id, person (id, name), unread, last_message_at, url) e people (com quem ela pode abrir uma: id, name, url); o unread do topo soma os canais e as conversas diretas. GET /chat/direct/{pessoa} (tracker:read; a pessoa pelo id ou e-mail; abre a conversa na primeira vez) traz person, url, people (vazio: não há @menção), unread, last_read_at, has_more e messages, com os mesmos parâmetros e campos da conversa do projeto, sem thread. POST /chat/direct/{pessoa} (tracker:write) envia {"text": "..."} (a outra pessoa é avisada no aparelho; thread_id dá 422); PATCH/DELETE /chat/direct/{pessoa}/{id} corrige e exclui (só quem escreveu; fora do histórico da empresa), POST/DELETE /chat/direct/{pessoa}/{id}/reactions reage e POST /chat/direct/{pessoa}/read marca como lida e GET /chat/direct/{pessoa}/issues?q= sugere as tarefas para citar (sem projeto do canal: as citadas na conversa e as abertas com a pessoa do token). Pessoa fora da equipe: 404; quem saiu da equipe depois deixa a conversa só para leitura (422 ao escrever). No MCP, as mesmas tools da conversa com person no lugar de project.
  • Apps das Conversas: quem escreve no canal sem ser uma pessoa (a mensagem vem com app e author_id null; ninguém corrige, o admin exclui). Cada app tem um manifesto: nome, o que pede (permissions), os eventos que escuta e o que cada canal escolhe. Os oficiais: task_updates (Avisos de tarefas: posta no canal quando uma tarefa do projeto é criada, muda de status, muda de responsável ou recebe comentário, com o cartão dela; cada canal escolhe os eventos) e automations (Automações: vem com o tracker e escreve quando uma regra de automação tem a ação "Enviar mensagem no canal"). A empresa instala (só admin e dono) e o PO/PM do projeto ou um admin liga em cada canal; a conversa direta fica fora dos apps. GET /apps (tracker:read) traz apps, o catálogo da empresa: key, name, summary, description, official, built_in, permissions (key, description), events, installed, installed_at e channels (em quantos canais está ligado). POST /apps/{key} (tracker:write) instala e DELETE /apps/{key} desinstala (desliga em todos os canais; as mensagens ficam); devolve key e installed. GET /projects/{ref}/chat/apps (tracker:read, quem participa da conversa) traz project, can_manage (pode ligar e desligar), can_install e apps (key, name, summary, built_in, installed, enabled e, no task_updates, events). PATCH /projects/{ref}/chat/apps/{key} (tracker:write, PO/PM ou admin) com {"enabled": true, "events": ["issue.created", "issue.status_changed", "issue.assigned", "comment.created"]} liga e escolhe os avisos (sem events, fica o que estava ou o padrão: tarefa criada e status mudou) e {"enabled": false} desliga; app não instalado dá 422. No MCP: list_chat_apps (com project, os do canal), install_chat_app e set_chat_app.
  • Google Meet (google_meet, app oficial): cria a reunião no canal, na conta Google de quem chama, e posta o cartão com o link de entrar. Cada pessoa conecta a própria conta Google uma vez, pelo navegador (a tela do Google não abre pela API). No canal, o app vem com account (configured, connected e email, a conta da pessoa do token). GET /apps/google_meet/account (tracker:read) traz configured, connected, email e connect_url (abra no navegador, logado no tracker); DELETE /apps/google_meet/account (tracker:write) desconecta e tira o acesso no Google. POST /projects/{ref}/chat/meet (tracker:write, quem participa da conversa) com {"title": "Planejamento da sprint"} (opcional) e "thread_id" (opcional: cria dentro da thread daquela mensagem) cria a sala e devolve project, message (id, thread_id, url) e meeting (url para entrar, code e title), 201. App desligado no canal: 403; sem a conta conectada: 422, com o link para conectar. A mensagem traz card: type meeting, provider google_meet, url, code, title e started_by (o nome de quem chamou). Na tela, o botão da câmera ao lado do campo ou /meet assunto. No MCP: start_meeting.