Contexto do contato para agente (pacote pronto)

v1.0.0

GEThttps://api.staging.growthaisystem.com/api/v1/contacts/{id}/context

ExigeAuthorization: Bearer gos_…— Chave de API (gos_…)· escoposcontacts.read

Tudo o que um agente de conversa precisa saber do contato, numa chamada só e sem nenhuma chamada de IA (só o que já está gravado): a ficha (o mesmo corpo de GET /contacts/{id}, com customFields = respostas de formulário, sem firstHumanTouchAt/lastHumanTouchAt), os negócios ABERTOS com o nome do funil e da etapa, as próximas reuniões e a última passada, as conversas em todos os canais (como em GET /conversations/{id}, com ai.paused e a janela de 24h), a linha do tempo de TODOS os canais (mensagens com texto ou transcrição do áudio, ligações com a transcrição vigente, e-mails, notas e eventos de reunião), e o resumo que a plataforma JÁ gravou na conversa principal.

Delta por turno: só a linha do tempo é recortada por since (o resto é o estado atual). Entra o item que ACONTECEU depois de since (at; mensagem: o envio no provedor) OU que foi GRAVADO aqui depois dele (mensagem que chegou atrasada com horário antigo). Exclusivo. Recomendado: mande em since o generatedAt do pacote anterior menos 5 minutos e descarte os itens cujo id você já viu — cobre a mensagem gravada durante a leitura anterior.

Escopos por seção: a rota exige contacts.read. opportunities exige opportunities.read (nomes de funil/etapa: + pipelines.read); appointments exige calendars.read; conversations, timeline e summary exigem conversations.read — que libera também a transcrição das ligações do contato na linha do tempo (os eventos de reunião: + calendars.read). Sem o escopo, a seção vem null e aparece em omittedSections — a rota não responde 403.

Tetos: linha do tempo limit 30 por padrão, até 100; texto de cada item cortado em maxTextChars (padrão 600, de 50 a 2000) com truncated: true; até 20 negócios, 10 próximas reuniões, 20 conversas, histórico das 20 reuniões mais recentes, resumo até 4000 caracteres. No pior caso (100 itens × 2000 caracteres) o corpo fica na casa de 300 KB; com os padrões, poucas dezenas de KB. Mais histórico: GET /interactions?contactId= (paginado).

includeSummary=false tira o único conteúdo derivado de IA (o summary).

Parâmetros de caminho

Entram no próprio endereço, no lugar das chaves.

idstringobrigatório
- tamanho mín. 1

Parâmetros de consulta

Vão na querystring, depois do ?.

sincestringopcional
limitintegeropcional
- padrão 30
- faixa 1–100
maxTextCharsintegeropcional
- padrão 600
- faixa 50–2000
includeSummarystringopcional
- padrão "true"
- um de"true""false"

Respostas

7 respostas documentadas — o código, o que ele significa nesta rota e a forma do corpo.

200Deu certoapplication/json

O pacote de contexto do contato. Seção null = a chave não tem o escopo dela (listada em omittedSections), ou, no summary, não há resumo gravado / includeSummary=false.

V1ContactContext

- idstring
- namestring
- phonestring | null
- emailstring | null
- companystring | null
- companyIdstring | null
- rolestring | null
- cpfstring | null
- notesstring | null
- tagsstring[]
- statusstring
  um de"active""archived""merged"
- ownerUserIdstring | null
- originstring
- customFieldsobjeto livre
  chave string
  valor qualquer valor JSON
- createdAtstring
- updatedAtstring
- urlstring
- sourcestring | null
  mediumstring | null
  campaignstring | null
  termstring | null
  contentstring | null
- firstHumanTouchAtstring | nullpode faltar
- lastHumanTouchAtstring | nullpode faltar
- humanTouchCountintegerpode faltar
  Quantos toques humanos este contato recebeu (cada mensagem, ligação, e-mail ou nota com actor: "user" em /interactions conta um). 0 = nenhum. Mesma fonte de firstHumanTouchAt/lastHumanTouchAt; só vem em GET /contacts/{id}.
  mín. 0
- firstHumanTouchChannelstring | nullpode faltar
  O canal do PRIMEIRO toque humano — o mesmo registro de firstHumanTouchAt, no vocabulário de channel de /interactions (whatsapp, instagram, facebook, call, email, note…). Dois toques no mesmo instante: vale o de menor id de /interactions. null = nunca houve toque humano.
Cada item — V1ContactContextOpportunity
- idstring
- titlestring
- pipelineIdstring
- stageIdstring
- contactIdstring
- statusstring
  um de"open""won""lost""abandoned"
- valueCentsinteger
- currencystring
- ownerUserIdstring | null
- temperaturestring
- tagsstring[]
- lossReasonstring | null
- expectedCloseAtstring | null
- wonAtstring | null
- wonRecordedAtstring | null
- lostAtstring | null
- lostRecordedAtstring | null
- lostAtStageIdstring | null
- customFieldsobjeto livre
  chave string
  valor qualquer valor JSON
- createdAtstring
- updatedAtstring
- sourcestring | null
- sourcestring | null
  mediumstring | null
  campaignstring | null
  termstring | null
  contentstring | null
- originstring
- stageChangedAtstring
- urlstring
- firstHumanTouchAtstring | nullpode faltar
- lastHumanTouchAtstring | nullpode faltar
- humanTouchCountintegerpode faltar
  Quantos toques humanos o contato deste negócio recebeu desde a CRIAÇÃO do negócio (cada mensagem, ligação, e-mail ou nota com actor: "user" em /interactions conta um). 0 = nenhum. Mesma fonte e mesmo recorte de firstHumanTouchAt/lastHumanTouchAt. Vem em GET /opportunities e em GET /opportunities/{id}.
  mín. 0
- firstHumanTouchChannelstring | nullpode faltar
  O canal do PRIMEIRO toque humano desde a criação do negócio — o mesmo registro de firstHumanTouchAt, no vocabulário de channel de /interactions (whatsapp, instagram, facebook, call, email, note…). Dois toques no mesmo instante: vale o de menor id de /interactions. null = ainda não houve toque humano.
- lastActivityAtstring | nullpode faltar
- pipelineNamestring | null
- stageNamestring | null
- Cada item — V1Appointment
  idstring
  contactIdstring | null
  contactNamestring | null
  opportunityIdstring | null
  titlestring
  startAtstring | null
  endAtstring | null
  locationstring | null
  conferenceUrlstring | null
  calendarKeystring | null
  assigneeUserIdstring | null
  statusstring
  um de"scheduled""canceled"
  outcomestring | null
  um de"realizada""noshow""reagendada"
  sourcestring
  createdAtstring
  createdByUserIdstring | null
  createdBySourcestring
  um de"crm""public_booking""api""automation""import""system""google_calendar"
  updatedAtstring
  canceledAtstring | null
  outcomeAtstring | null
  recoveredFromAppointmentIdstring | null
  externalIdstringpode faltar
  Só em source: "google_calendar": o id do evento no Google Agenda (o id do events.list).
  calendarIdstringpode faltar
  Só em source: "google_calendar": a agenda do Google de onde o evento veio, como a conexão a guarda (primary = a agenda principal da conta conectada). O dono da conta é o assigneeUserId.
  allDaybooleanpode faltar
  Só em source: "google_calendar": evento de dia inteiro (o startAt é a meia-noite UTC do dia).
  externalStatusstringpode faltar
  Só em source: "google_calendar": a situação crua no Google — confirmed, tentative ou cancelled. status traduz para o vocabulário da API (cancelled → canceled; as outras → scheduled).
  visibilitystringpode faltar
  Só em source: "google_calendar": a privacidade que o dono escolheu para a agenda conectada, a mesma da tela da agenda. busy ("só ocupado") = a API mostra exatamente o que a tela mostra: o horário, o dono e o título "Ocupado" — attendees e htmlLink vêm null. details = o título real, os convidados e o link (evento sem título no Google também sai "Ocupado", como na tela).
  um de"details""busy"
  Só em source: "google_calendar": os convidados com a resposta de cada um. [] = evento sem convidado. null = agenda em modo "só ocupado" (visibility: "busy"), ou evento espelhado antes desta versão da API que ainda não passou pelo próximo sync (o espelho regrava cada agenda pelo menos uma vez por dia).
  Cada item — V1CalendarAttendee
  emailstring
  E-mail do convidado (minúsculas).
  responseStatusstring | null
  A resposta ao convite, no vocabulário do Google: needsAction, accepted, tentative ou declined.
  organizerboolean
  true = quem organiza o evento.
  selfboolean
  true = a própria conta Google conectada (o dono da agenda).
  htmlLinkstring | nullpode faltar
  Só em source: "google_calendar": o link do evento no Google Agenda (abre para quem tem acesso à agenda). null nos mesmos casos de attendees.
- idstring
  contactIdstring | null
  contactNamestring | null
  opportunityIdstring | null
  titlestring
  startAtstring | null
  endAtstring | null
  locationstring | null
  conferenceUrlstring | null
  calendarKeystring | null
  assigneeUserIdstring | null
  statusstring
  um de"scheduled""canceled"
  outcomestring | null
  um de"realizada""noshow""reagendada"
  sourcestring
  createdAtstring
  createdByUserIdstring | null
  createdBySourcestring
  um de"crm""public_booking""api""automation""import""system""google_calendar"
  updatedAtstring
  canceledAtstring | null
  outcomeAtstring | null
  recoveredFromAppointmentIdstring | null
  externalIdstringpode faltar
  Só em source: "google_calendar": o id do evento no Google Agenda (o id do events.list).
  calendarIdstringpode faltar
  Só em source: "google_calendar": a agenda do Google de onde o evento veio, como a conexão a guarda (primary = a agenda principal da conta conectada). O dono da conta é o assigneeUserId.
  allDaybooleanpode faltar
  Só em source: "google_calendar": evento de dia inteiro (o startAt é a meia-noite UTC do dia).
  externalStatusstringpode faltar
  Só em source: "google_calendar": a situação crua no Google — confirmed, tentative ou cancelled. status traduz para o vocabulário da API (cancelled → canceled; as outras → scheduled).
  visibilitystringpode faltar
  Só em source: "google_calendar": a privacidade que o dono escolheu para a agenda conectada, a mesma da tela da agenda. busy ("só ocupado") = a API mostra exatamente o que a tela mostra: o horário, o dono e o título "Ocupado" — attendees e htmlLink vêm null. details = o título real, os convidados e o link (evento sem título no Google também sai "Ocupado", como na tela).
  um de"details""busy"
  Só em source: "google_calendar": os convidados com a resposta de cada um. [] = evento sem convidado. null = agenda em modo "só ocupado" (visibility: "busy"), ou evento espelhado antes desta versão da API que ainda não passou pelo próximo sync (o espelho regrava cada agenda pelo menos uma vez por dia).
  Cada item — V1CalendarAttendee
  emailstring
  E-mail do convidado (minúsculas).
  responseStatusstring | null
  A resposta ao convite, no vocabulário do Google: needsAction, accepted, tentative ou declined.
  organizerboolean
  true = quem organiza o evento.
  selfboolean
  true = a própria conta Google conectada (o dono da agenda).
  htmlLinkstring | nullpode faltar
  Só em source: "google_calendar": o link do evento no Google Agenda (abre para quem tem acesso à agenda). null nos mesmos casos de attendees.
Cada item — V1Conversation
- idstring
- channelstring
- connectionIdstring | null
- contactIdstring | null
- idstring
  namestring
  phonestring | null
  emailstring | null
- contactDisplaystring | null
- contactPhonestring | null
- assignedUserIdstring | null
- humanAssignedboolean
- assignedAtstring | null
- lastMessageAtstring | null
- lastMessageDirectionstring | null
  um de"inbound""outbound"
- lastMessageActorstring | null
  um de"user""contact""ia""automation""system""api""unknown"
- archivedboolean
- pausedboolean
  pausedUntilstring | null
  pausedReasonstring | null
- appliesboolean
  openboolean
  expiresAtstring | null
- createdAtstring
- updatedAtstring
- Cada item — V1ContactTimelineItem
  idstring
  kindstring
  um de"message""call""email""note""meeting"
  channelstring
  directionstring | null
  um de"inbound""outbound"
  actorstring
  um de"user""contact""ia""automation""system""api""unknown"
  userIdstring | null
  conversationIdstring | null
  connectionIdstring | null
  opportunityIdstring | null
  atstring
  textstring | null
  textSourcestring | null
  um de"text""transcription""call_transcript""subject""note""meeting_title"
  truncatedboolean
  messageTypestring | null
  transcriptionStatusstring | null
  hasMediaboolean
  durationSecinteger | null
  statusstring | null
  statusReasonstring | null
  appointmentIdstring
  eventstring
  titlestring | null
  startAtstring | null
  outcomestring | null
  reasonstring | null
- hasMoreboolean
- sincestring | null
- conversationIdstring
- textstring
- truncatedboolean
- generatedBy"platform"
  sempre "platform"
- updatedAtstring | null
Cada item da lista
- sectionstring
  um de"opportunities""opportunities.stageNames""appointments""conversations""timeline""timeline.meetings""summary"
- reason"missing_scope"
  sempre "missing_scope"
- requiredScopesstring[]
generatedAtstring

Definição

GET/contacts/{id}/context

Exemplo

https://api.staging.growthaisystem.com/api/v1/contacts/SEU_ID_AQUI/context

Requisição

curl "https://api.staging.growthaisystem.com/api/v1/contacts/SEU_ID_AQUI/context" \
  -H "Authorization: Bearer gos_SEU_TOKEN_AQUI"

Isto chama a API de verdade. A requisição sai do seu navegador direto para https://api.staging.growthaisystem.com — dado real, do workspace da chave que você colar. Em escritas, o efeito é permanente.

Chave de APIBearerobrigatório

Vai no cabeçalho Authorization: Bearer …. Ela nunca aparece no cURL copiável nem sai desta aba.

Lembrar nesta aba — some ao fechá-la. Não marque em computador compartilhado: a chave dá acesso ao workspace inteiro dentro dos escopos dela.

Parâmetros de caminho

Entram no próprio endereço, no lugar das chaves.

idtextoobrigatório

Parâmetros de consulta

Marque os que devem ir na querystring. Digitar já marca.

sincetexto

limitinteiro

maxTextCharsinteiro

includeSummaryenum

Vai sair assim

GEThttps://api.staging.growthaisystem.com/api/v1/contacts/{id}/context

O botão copia o cURL equivalente — com gos_SEU_TOKEN_AQUI no lugar da sua chave.

⌘Enter

Resposta

{
  "contact": {
    "id": "8f14c0b2-91a7-4c3d-9b6e-2a5d7f0e1c44",
    "name": "Mariana Alves",
    "phone": "5511987654321",
    "email": "mariana.alves@lojaverde.com.br",
    "company": "Loja Verde Comércio Ltda",
    "companyId": null,
    "role": "Gerente de Compras",
    "cpf": "529.982.247-25",
    "notes": "Pediu proposta de 300 unidades para dezembro.",
    "tags": [
      "Cliente VIP",
      "canal:yayforms"
    ],
    "status": "active",
    "ownerUserId": "c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
    "origin": "api",
    "customFields": {
      "segmento": "varejo",
      "ticket_medio": 4500
    },
    "createdAt": "2026-09-12T18:04:51.221Z",
    "updatedAt": "2026-09-13T11:27:03.994Z",
    "url": "https://app.growthaisystem.com/crm/contatos?contactId=8f14c0b2-91a7-4c3d-9b6e-2a5d7f0e1c44",
    "utm": {
      "source": "instagram",
      "medium": "cpc",
      "campaign": "black-friday-2026",
      "term": null,
      "content": "criativo-carrossel-a"
    },
    "firstHumanTouchAt": "2026-09-12T18:41:07.310Z",
    "lastHumanTouchAt": "2026-09-13T09:12:44.008Z",
    "humanTouchCount": 7,
    "firstHumanTouchChannel": "whatsapp"
  },
  "opportunities": [
    {
      "id": "<texto>",
      "title": "<texto>",
      "pipelineId": "<texto>",
      "stageId": "<texto>",
      "contactId": "<texto>",
      "status": "open",
      "valueCents": 0,
      "currency": "<texto>",
      "ownerUserId": null,
      "temperature": "<texto>",
      "tags": [
        "<texto>"
      ],
      "lossReason": null,
      "expectedCloseAt": null,
      "wonAt": null,
      "wonRecordedAt": null,
      "lostAt": null,
      "lostRecordedAt": null,
      "lostAtStageId": null,
      "customFields": {},
      "createdAt": "<texto>",
      "updatedAt": "<texto>",
      "source": null,
      "utm": {
        "source": "instagram",
        "medium": "cpc",
        "campaign": "black-friday-2026",
        "term": null,
        "content": "criativo-carrossel-a"
      },
      "origin": "<texto>",
      "stageChangedAt": "<texto>",
      "url": "<texto>",
      "firstHumanTouchAt": null,
      "lastHumanTouchAt": null,
      "humanTouchCount": 0,
      "firstHumanTouchChannel": null,
      "lastActivityAt": null,
      "pipelineName": null,
      "stageName": null
    }
  ],
  "appointments": {
    "upcoming": [
      {
        "id": "9d2e7c41-3f86-4b52-a1c9-6e0f8b47d215",
        "contactId": "c4b8f2a1-9e3d-4a7b-8f21-0d5c6e9a1b34",
        "contactName": "Mariana Alves",
        "opportunityId": "1a6b9c34-7d25-48ef-b013-5c82f7a9d6e0",
        "title": "Demonstração — Mariana Alves",
        "startAt": "2026-09-23T12:00:00.000Z",
        "endAt": "2026-09-23T12:45:00.000Z",
        "location": null,
        "conferenceUrl": "https://meet.google.com/xqz-mnpr-tvk",
        "calendarKey": "demo",
        "assigneeUserId": "k7QxZm3Rt9VbN2wP5cLdH8sYjF1aGu4E",
        "status": "scheduled",
        "outcome": null,
        "source": "crm",
        "createdAt": "2026-09-13T14:22:08.431Z",
        "createdByUserId": null,
        "createdBySource": "api",
        "updatedAt": "2026-09-13T14:22:08.431Z",
        "canceledAt": null,
        "outcomeAt": null,
        "recoveredFromAppointmentId": null
      }
    ],
    "lastPast": {
      "id": "9d2e7c41-3f86-4b52-a1c9-6e0f8b47d215",
      "contactId": "c4b8f2a1-9e3d-4a7b-8f21-0d5c6e9a1b34",
      "contactName": "Mariana Alves",
      "opportunityId": "1a6b9c34-7d25-48ef-b013-5c82f7a9d6e0",
      "title": "Demonstração — Mariana Alves",
      "startAt": "2026-09-23T12:00:00.000Z",
      "endAt": "2026-09-23T12:45:00.000Z",
      "location": null,
      "conferenceUrl": "https://meet.google.com/xqz-mnpr-tvk",
      "calendarKey": "demo",
      "assigneeUserId": "k7QxZm3Rt9VbN2wP5cLdH8sYjF1aGu4E",
      "status": "scheduled",
      "outcome": null,
      "source": "crm",
      "createdAt": "2026-09-13T14:22:08.431Z",
      "createdByUserId": null,
      "createdBySource": "api",
      "updatedAt": "2026-09-13T14:22:08.431Z",
      "canceledAt": null,
      "outcomeAt": null,
      "recoveredFromAppointmentId": null
    }
  },
  "conversations": [
    {
      "id": "b2d95f41-0c8e-4a17-91f6-7e3c5a8b2d40",
      "channel": "whatsapp",
      "connectionId": "5a8e2c17-93b4-4d0f-8671-ea5c2b9f7401",
      "contactId": "3f7b1c92-58ad-4f60-9e2b-c41d7a0e85b3",
      "contact": {
        "id": "3f7b1c92-58ad-4f60-9e2b-c41d7a0e85b3",
        "name": "Mariana Costa",
        "phone": "+5511987654321",
        "email": null
      },
      "contactDisplay": "Mariana",
      "contactPhone": "5511987654321",
      "assignedUserId": null,
      "humanAssigned": false,
      "assignedAt": null,
      "lastMessageAt": "2026-10-13T14:02:11.000Z",
      "lastMessageDirection": "inbound",
      "lastMessageActor": "contact",
      "archived": false,
      "ai": {
        "paused": false,
        "pausedUntil": null,
        "pausedReason": null
      },
      "messagingWindow": {
        "applies": true,
        "open": true,
        "expiresAt": "2026-10-14T14:02:11.000Z"
      },
      "createdAt": "2026-10-13T14:02:11.418Z",
      "updatedAt": "2026-10-13T14:02:11.418Z"
    }
  ],
  "timeline": {
    "items": [
      {
        "id": "inbox_message:9c1f4b2e-7a3d-4e8c-b5f1-2d6a90c3e741",
        "kind": "message",
        "channel": "whatsapp",
        "direction": "inbound",
        "actor": "contact",
        "userId": null,
        "conversationId": "b2d95f41-0c8e-4a17-91f6-7e3c5a8b2d40",
        "connectionId": "5a8e2c17-93b4-4d0f-8671-ea5c2b9f7401",
        "opportunityId": null,
        "at": "2026-10-13T14:02:11.000Z",
        "text": "Oi! Vi o anúncio de vocês, como funciona a mentoria?",
        "textSource": "text",
        "truncated": false,
        "messageType": "text",
        "transcriptionStatus": null,
        "hasMedia": false,
        "durationSec": null,
        "status": "received",
        "statusReason": null,
        "meeting": null
      }
    ],
    "hasMore": false,
    "since": null
  },
  "summary": {
    "conversationId": "<texto>",
    "text": "<texto>",
    "truncated": false,
    "generatedBy": "platform",
    "updatedAt": null
  },
  "omittedSections": [
    {
      "section": "opportunities",
      "reason": "missing_scope",
      "requiredScopes": [
        "<texto>"
      ]
    }
  ],
  "generatedAt": "<texto>"
}