Pular para o conteúdo
Contatos

Contexto de vários contatos (lote)

v1.0.0
GEThttps://api.growthaisystem.com/api/v1/contacts/context
  • ExigeAuthorization: Bearer gos_…— Chave de API (gos_…)· escoposcontacts.read

O MESMO pacote de GET /contacts/{id}/context para até 25 contatos numa chamada: ids=a,b,c. Cada contato é lido pela mesma função da rota de um contato — mesmas seções, mesmos escopos por seção (seção sem escopo vem null e entra em omittedSections de CADA pacote), mesmos tetos por contato — e os parâmetros since, limit, maxTextChars e includeSummary valem para todos.

Ids: separados por vírgula, sem espaço obrigatório. A resposta traz um item por id DISTINTO, na ordem da primeira aparição. Id repetido é respondido uma vez e listado em duplicateIds. Id que não existe neste workspace (ou está na Lixeira, ou foi mesclado) vem com status: "not_found" e context: null — a chamada não vira 404 por causa dele. Mais de 25 ids (contando os repetidos) = 400.

Custo: os contatos são lidos um de cada vez (a chamada segura no máximo 2 conexões do banco, como a rota de um contato), então a resposta demora mais quanto mais ids. No pior caso (25 contatos × 100 itens × 2000 caracteres) o corpo passa de 5 MB; com os padrões, algumas centenas de KB.

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"
  • idsstringobrigatório

    Ids dos contatos separados por vírgula, de 1 a 25 (os repetidos contam). Id repetido é respondido UMA vez e listado em duplicateIds; id que não existe neste workspace (ou está na Lixeira) vem com status: "not_found" — a chamada não vira 404.

    • tamanho 1–2025

Respostas

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

200Deu certoapplication/json

Um item por contato pedido (sem repetição): o pacote de contexto, ou not_found. Os ids repetidos saem em duplicateIds.

V1ContactContextBatch

  • Um item por id DISTINTO, na ordem em que cada um apareceu pela primeira vez em ids.

    Cada item — V1ContactContextBatchItem

    • contactIdstring

      O id pedido, sem espaço nas pontas.

    • statusstring

      ok = o pacote está em context. not_found = não existe contato com esse id neste workspace (ou ele foi mesclado, ou está na Lixeira) — o mesmo caso que dá 404 em GET /contacts/{id}/context.

      • um de"ok""not_found"

    • O MESMO pacote de GET /contacts/{id}/context, com as mesmas seções por escopo. null quando status é not_found.

        • 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
  • duplicateIdsstring[]

    Ids que vieram repetidos em ids — cada um respondido uma vez só em data. [] = nenhum repetido.

  • generatedAtstring

    Quando o lote começou a ser lido (ISO-8601). Cada pacote traz também o seu generatedAt.