Leitura de uma conversa

GET

/v1/conversations/{channel}/{conversationId}/reading

const url = 'https://developers.nexo.winningsales.com.br/v1/conversations/example/example/reading';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://developers.nexo.winningsales.com.br/v1/conversations/example/example/reading \
  --header 'Authorization: Bearer <token>'

O que o Nexo já leu da conversa, em qualquer canal: participantes e papel na compra, objeções e se foram tratadas, dores, compromissos, próximo passo, processo de decisão, sinais de compra, concorrentes, a etapa que a conversa sustenta e um resumo, cada item com os trechos que o sustentam. A leitura já está pronta: ler não consome IA. O vendedor só enxerga as conversas dos próprios negócios e as próprias; admin e líder de vendas enxergam as da empresa. Conteúdo de conversa na íntegra: exige o escopo conversations:read e cada leitura fica registrada na atividade da empresa.

Authorizations

bearer

Parameters

Path Parameters

conversationId

required

Id da conversa no canal

channel

required

Canal: meeting, note, call, email, whatsapp ou crm_whatsapp

Responses

200

A leitura da conversa

application/json

object

channel

required

Canal da conversa: reunião gravada (meeting), nota do CRM (note), ligação registrada (call), e-mail (email) ou sessão de WhatsApp (whatsapp)

string

Allowed values: meeting note call email whatsapp crm_whatsapp

conversationId

required

Id da reunião, do engajamento do CRM ou da sessão de WhatsApp

string

status

required

A leitura desta conversa está pronta

string

Allowed values: read

readingVersion

required

Versão da leitura. Quando a versão muda, a conversa é lida de novo

integer

readAt

required

Quando o Nexo leu a conversa

string format: date-time

nullable

modelId

required

Modelo que fez a leitura

string

nullable

extraction

required

O que o Nexo leu da conversa, na taxonomia fixa. Todo item cita os trechos (e1, e2…) que o sustentam; é leitura, não fato do CRM

object

participants

required

Array<object>

<= 12 items

object

speakerRef

required

Participant id (p1, p2…) from the participant list.

string

/^p\d+$/

buyingRole

required

Role in the purchase, only with evidence in this conversation; unknown otherwise. Only for customer-side participants.

string

Allowed values: decision_maker budget_holder influencer technical_evaluator user unknown

statedJobTitle

required

Job title as said in the conversation, or null.

string

nullable <= 80 characters

excerptRefs

required

Ids of the transcript excerpts (e1, e2…) that say this. Only ids that exist in the transcript; at least one.

Array<string>

<= 5 items

stakeholdersMentioned

required

Array<object>

<= 8 items

object

name

required

Name when said (“Marcelo”); null for a body or an unnamed person.

string

nullable <= 80 characters

descriptor

required

How they are described: “diretor financeiro”, “o conselho”, “sócio”.

string

<= 80 characters

buyingRole

required

Exactly one of these values; a board or committee that approves is decision_maker.

string

Allowed values: decision_maker budget_holder influencer technical_evaluator user unknown

presentAs

required

Participant id (p1, p2…) from the participant list.

string

nullable /^p\d+$/

excerptRefs

required

Ids of the transcript excerpts (e1, e2…) that say this. Only ids that exist in the transcript; at least one.

Array<string>

<= 5 items

objections

required

Array<object>

<= 8 items

object

code

required

Competitor only when the buyer compares another vendor (price, feature, proposal) with this one; a vendor only mentioned, even to put pressure, goes to mentionedCompanies and is not an objection.

string

Allowed values: price timing authority implementation competitor status_quo trust_risk scope_fit contract_terms other

statement

required

The buyer’s or rep’s own words, summarized in Brazilian Portuguese without changing the meaning.

string

<= 200 characters

mention

required

Raised when it first appears here; revisited when someone brings back something from before.

string

Allowed values: raised revisited

status

required

Handled only when the rep answered with substance and the buyer did not reassert it later in this conversation. Taking it to someone else, promising to check or send something later, or changing the subject is not an answer: open.

string

Allowed values: open handled

raisedBy

required

Customer-side participant who raised it.

string

/^p\d+$/

excerptRefs

required

Ids of the transcript excerpts (e1, e2…) that say this. Only ids that exist in the transcript; at least one.

Array<string>

<= 5 items

responseExcerptRefs

required

Ids of the transcript excerpts (e1, e2…) that say this. Only ids that exist in the transcript; at least one.

Array<string>

nullable <= 5 items

pains

required

Array<object>

<= 6 items

object

code

required

string

Allowed values: revenue_loss lack_of_visibility manual_work tool_limitation cost quality_errors growth_capacity compliance_risk people_dependency other

statement

required

The buyer’s or rep’s own words, summarized in Brazilian Portuguese without changing the meaning.

string

<= 200 characters

excerptRefs

required

Ids of the transcript excerpts (e1, e2…) that say this. Only ids that exist in the transcript; at least one.

Array<string>

<= 5 items

commitments

required

Array<object>

<= 8 items

object

owner

required

string

Allowed values: rep buyer

speakerRef

required

Participant id (p1, p2…) from the participant list.

string

/^p\d+$/

what

required

What was promised, e.g. “enviar simulação com três cenários”.

string

<= 160 characters

dueText

required

The due date as said (“até sexta”), or null.

string

nullable <= 40 characters

dueDate

required

The due date resolved from the meeting date, YYYY-MM-DD, or null.

string

nullable /^\d{4}-\d{2}-\d{2}$/

excerptRefs

required

Ids of the transcript excerpts (e1, e2…) that say this. Only ids that exist in the transcript; at least one.

Array<string>

<= 5 items

deliveryMentions

required

Array<object>

<= 6 items

object

what

required

Something previously promised that is mentioned as delivered (“recebi a proposta”).

string

<= 160 characters

excerptRefs

required

Ids of the transcript excerpts (e1, e2…) that say this. Only ids that exist in the transcript; at least one.

Array<string>

<= 5 items

nextStep

required

A concrete step both sides agreed on. An open-ended or conditional ending (“se fizer sentido a gente conversa”) is not one.

object

description

required

string

<= 160 characters

owner

required

string

Allowed values: rep buyer both none

dateText

required

string

nullable <= 40 characters

date

required

string

nullable /^\d{4}-\d{2}-\d{2}$/

agreedByBuyer

required

True only when the buyer agreed to or proposed this next step.

boolean

excerptRefs

required

Ids of the transcript excerpts (e1, e2…) that say this. Only ids that exist in the transcript; at least one.

Array<string>

<= 5 items

decisionProcess

required

Array<object>

<= 8 items

object

kind

required

Exactly one of these values. The person who decides or approves is approver; buying roles are not valid here.

string

Allowed values: approver approval_step decision_date spending_limit budget decision_criteria buyer_deadline

statement

required

The buyer’s or rep’s own words, summarized in Brazilian Portuguese without changing the meaning.

string

<= 200 characters

amountInCents

required

Only for spending_limit and budget, when an amount is said; in cents.

integer

nullable

date

required

Only for decision_date and buyer_deadline, when a date is said.

string

nullable /^\d{4}-\d{2}-\d{2}$/

excerptRefs

required

Ids of the transcript excerpts (e1, e2…) that say this. Only ids that exist in the transcript; at least one.

Array<string>

<= 5 items

buyingSignals

required

Array<object>

<= 6 items

object

kind

required

string

Allowed values: asked_for_proposal asked_implementation_details asked_for_reference sizing_the_deal brought_new_stakeholder requested_next_step asked_contract

statement

required

The buyer’s or rep’s own words, summarized in Brazilian Portuguese without changing the meaning.

string

<= 200 characters

excerptRefs

required

Ids of the transcript excerpts (e1, e2…) that say this. Only ids that exist in the transcript; at least one.

Array<string>

<= 5 items

postponements

required

Array<object>

<= 3 items

object

reason

required

Why it was pushed back. When the buyer gives a reason (“esse mês complicou”), also return it in objections (timing or the matching code).

string

<= 160 characters

newDate

required

string

nullable /^\d{4}-\d{2}-\d{2}$/

newDateProposedBy

required

string

Allowed values: buyer rep none

excerptRefs

required

Ids of the transcript excerpts (e1, e2…) that say this. Only ids that exist in the transcript; at least one.

Array<string>

<= 5 items

mentionedCompanies

required

Array<object>

<= 8 items

object

name

required

string

<= 80 characters

kind

required

string

Allowed values: competitor partner reference other

comparison

required

For competitor only: how it was compared (“30% mais barato”).

string

nullable <= 160 characters

excerptRefs

required

Ids of the transcript excerpts (e1, e2…) that say this. Only ids that exist in the transcript; at least one.

Array<string>

<= 5 items

customerTools

required

Array<object>

<= 8 items

object

name

required

string

<= 80 characters

category

required

string

Allowed values: crm erp spreadsheet communication industry_system other

usage

required

string

Allowed values: current evaluating leaving

excerptRefs

required

Ids of the transcript excerpts (e1, e2…) that say this. Only ids that exist in the transcript; at least one.

Array<string>

<= 5 items

repOffers

required

Array<object>

<= 6 items

object

topic

required

Minimum_price only when the rep accepts a price below the list or a floor for this deal; quoting the price, even for their volume, is not an offer and goes to the summary.

string

Allowed values: discount minimum_price deadline payment_terms integration scope implementation

statement

required

What the rep offered or promised, e.g. “8% de desconto com contrato anual”.

string

<= 200 characters

speakerRef

required

Company-side participant who offered it.

string

/^p\d+$/

excerptRefs

required

Ids of the transcript excerpts (e1, e2…) that say this. Only ids that exist in the transcript; at least one.

Array<string>

<= 5 items

arrival

How the customer says they came to know the company or reached it. Only when the customer says it, or the text reports the customer saying it; never inferred from the deal, the CRM or the rep alone. Null when not said.

object

channel

required

Referral: a customer or acquaintance recommended the company; partner: an accountant, integrator, consultancy or other partner brought them; event: an event, talk or fair; social_media: LinkedIn, Instagram or another social network; content: the site, a search, a podcast, a video or an article; ads: an ad; outbound: the company reached out first (a call, e-mail or message the customer did not ask for); other: none of these, said in the statement.

string

Allowed values: referral partner event social_media content ads outbound other

statement

required

The buyer’s or rep’s own words, summarized in Brazilian Portuguese without changing the meaning.

string

<= 200 characters

referrer

required

Who referred them or which event, partner or profile, when said (“o João da Conecta”, “a palestra do RD Summit”); null otherwise.

string

nullable <= 80 characters

excerptRefs

required

Ids of the transcript excerpts (e1, e2…) that say this. Only ids that exist in the transcript; at least one.

Array<string>

<= 5 items

salesTeam

Size of the customer’s own sales team, when the conversation says it. It is the buyer’s team, never the rep’s company. Null when not said.

object

size

required

Number of people selling on the customer side, when a number is said (“somos 12 vendedores”); null when only described.

integer

nullable <= 100000

statement

required

The buyer’s or rep’s own words, summarized in Brazilian Portuguese without changing the meaning.

string

<= 200 characters

excerptRefs

required

Ids of the transcript excerpts (e1, e2…) that say this. Only ids that exist in the transcript; at least one.

Array<string>

<= 5 items

stageEvidence

required

The most advanced canonical phase this conversation supports with evidence; null when none.

object

phase

required

string

Allowed values: prospecting discovery qualification solution proposal negotiation

rationale

required

string

<= 160 characters

excerptRefs

required

Ids of the transcript excerpts (e1, e2…) that say this. Only ids that exist in the transcript; at least one.

Array<string>

<= 5 items

summaryBullets

required

3 to 6 bullets for the deal review when the conversation has sales content.

Array<object>

<= 6 items

object

text

required

string

<= 200 characters

excerptRefs

required

Ids of the transcript excerpts (e1, e2…) that say this. Only ids that exist in the transcript; at least one.

Array<string>

<= 5 items

schemaVersion

required

string

Allowed values: conversation-extraction/1

taxonomyVersion

required

string

Allowed values: 2026-09.1

readBy

Which reading wrote this extraction: the full one, or the cheaper profile-only one of the history re-read

object

kind

required

string

Allowed values: full profile

modelId

required

string

nullable

excerpts

required

Os trechos citados pela leitura, na ordem da conversa

Array<object>

object

ref

required

Referência curta do trecho (e1, e2…), a mesma que as leituras do Nexo citam

string

text

required

O texto do trecho, como foi dito ou escrito

string

speakerName

required

Quem falou ou escreveu o trecho

string

nullable

required

Quando a mensagem foi enviada, no WhatsApp; nulo nos outros canais

string format: date-time

nullable

Example

{
  "channel": "meeting",
  "status": "read",
  "extraction": {
    "participants": [
      {
        "buyingRole": "decision_maker"
      }
    ],
    "stakeholdersMentioned": [
      {
        "buyingRole": "decision_maker"
      }
    ],
    "objections": [
      {
        "code": "price",
        "mention": "raised",
        "status": "open"
      }
    ],
    "pains": [
      {
        "code": "revenue_loss"
      }
    ],
    "commitments": [
      {
        "owner": "rep"
      }
    ],
    "nextStep": {
      "owner": "rep"
    },
    "decisionProcess": [
      {
        "kind": "approver"
      }
    ],
    "buyingSignals": [
      {
        "kind": "asked_for_proposal"
      }
    ],
    "postponements": [
      {
        "newDateProposedBy": "buyer"
      }
    ],
    "mentionedCompanies": [
      {
        "kind": "competitor"
      }
    ],
    "customerTools": [
      {
        "category": "crm",
        "usage": "current"
      }
    ],
    "repOffers": [
      {
        "topic": "discount"
      }
    ],
    "arrival": {
      "channel": "referral"
    },
    "stageEvidence": {
      "phase": "prospecting"
    },
    "schemaVersion": "conversation-extraction/1",
    "taxonomyVersion": "2026-09.1",
    "readBy": {
      "kind": "full"
    }
  }
}

400

Canal inválido

application/json

object

type

required

Stable machine-readable error code (e.g. identity.email_already_in_use)

string

title

required

Error class name

string

status

required

HTTP status code

integer

detail

required

Human-readable message, safe to display to end users

string

requestId

required

Correlation id — send it to support to locate the full trail

string

nullable

meta

Structured details safe for the frontend (field errors, ids)

object

key

additional properties

Example ^generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "requestId": "example",
  "meta": {
    "additionalProperty": "example"
  }
}

401

Token ausente, inválido, expirado ou revogado

application/json

object

type

required

Stable machine-readable error code (e.g. identity.email_already_in_use)

string

title

required

Error class name

string

status

required

HTTP status code

integer

detail

required

Human-readable message, safe to display to end users

string

requestId

required

Correlation id — send it to support to locate the full trail

string

nullable

meta

Structured details safe for the frontend (field errors, ids)

object

key

additional properties

Example

{
  "type": "public_api.invalid_credential",
  "title": "InvalidCredentialError",
  "status": 401,
  "detail": "Token de acesso inválido, expirado ou revogado. Crie um novo token de acesso no Nexo.",
  "requestId": "019fcae7-3e54-755a-8458-bdb605b324bb"
}

403

Papel, escopo do token ou plano não permitem a operação

application/json

object

type

required

Stable machine-readable error code (e.g. identity.email_already_in_use)

string

title

required

Error class name

string

status

required

HTTP status code

integer

detail

required

Human-readable message, safe to display to end users

string

requestId

required

Correlation id — send it to support to locate the full trail

string

nullable

meta

Structured details safe for the frontend (field errors, ids)

object

key

additional properties

Example

{
  "type": "public_api.insufficient_scope",
  "title": "InsufficientScopeError",
  "status": 403,
  "detail": "Este token não tem o escopo conversations:read, exigido por esta operação. Gere um token com esse escopo.",
  "requestId": "019fcae7-3e54-755a-8458-bdb605b324bb",
  "meta": {
    "operation": "conversations.reading",
    "scope": "conversations:read"
  }
}

404

Conversa ainda não lida ou fora da visibilidade

application/json

object

type

required

Stable machine-readable error code (e.g. identity.email_already_in_use)

string

title

required

Error class name

string

status

required

HTTP status code

integer

detail

required

Human-readable message, safe to display to end users

string

requestId

required

Correlation id — send it to support to locate the full trail

string

nullable

meta

Structured details safe for the frontend (field errors, ids)

object

key

additional properties

Example

{
  "type": "conversations.conversation_unavailable",
  "title": "ConversationUnavailableError",
  "status": 404,
  "detail": "Esta conversa não está disponível.",
  "requestId": "019fcae7-3e54-755a-8458-bdb605b324bb",
  "meta": {
    "channel": "whatsapp",
    "conversationId": "019fcae7-3e54-755a-8458-bdb605b324aa"
  }
}

429

Limite de chamadas da empresa ou do token atingido

application/json

object

type

required

Stable machine-readable error code (e.g. identity.email_already_in_use)

string

title

required

Error class name

string

status

required

HTTP status code

integer

detail

required

Human-readable message, safe to display to end users

string

requestId

required

Correlation id — send it to support to locate the full trail

string

nullable

meta

Structured details safe for the frontend (field errors, ids)

object

key

additional properties

Example

{
  "type": "public_api.rate_limited",
  "title": "PublicRateLimitedError",
  "status": 429,
  "detail": "Muitas chamadas em pouco tempo. Tente de novo em 12 segundos.",
  "requestId": "019fcae7-3e54-755a-8458-bdb605b324bb",
  "meta": {
    "class": "content",
    "limitedBy": "company",
    "limit": 120,
    "windowSeconds": 60,
    "retryAfterSeconds": 12
  }
}

Leitura de uma conversa

Authorizations

Parameters

Path Parameters

Responses

200

Example

400

Example generated

401

Example

403

Example

404

Example

429

Example

Example ^generated