Pular para o conteúdo
MSP Desk para desenvolvedores

Lista as conversas do MSP Talks vinculadas a um ticket

GET
/v1/tickets/{ticketId}/chat-sessions
Code sample: Shell / cURL
curl --request GET \
  --url 'https://public-api.mspdesk.com.br/v1/tickets/1/chat-sessions?filter%5Bid%5D%5Bin%5D=1%2C2%2C3&limit=25&sort=-createdAt&fields=id%2CsessionId%2CsessionNumber&expand=customer%2Cagent' \
  --header 'Authorization: Bearer <token>'

Escopo exigido: tickets:read. Paginação por cursor opaco (?cursor=), nunca por página/offset — use nextCursor da resposta anterior. A ordenação padrão é -id (a mais recente primeiro); createdAt também ordena.

updatedAt é lastNoteAt quando há anotação e createdAt quando não há — a anotação é a única alteração que um vínculo sofre. Ele filtra, mas não ordena: o valor combina duas colunas e não serve de chave de paginação estável.

Nenhuma chamada ao MSP Talks acontece na leitura: o que volta é o que o Desk gravou quando a conversa foi vinculada.

Autorizações

Seção intitulada “Authorizations”

Parâmetros

Seção intitulada “Parameters”

Parâmetros de caminho

Seção intitulada “Path Parameters”
ticketId
required
integer format: int64

ID do ticket

Exemplo
1

Parâmetros de consulta

Seção intitulada “Query Parameters”
filter[id][eq]
integer format: int64

Filtra por id igual ao valor informado.

filter[id][in]
string
Exemplo
1,2,3

Filtra por id igual a um dos valores informados, separados por vírgula (até 100).

filter[sessionId][eq]
string

Filtra por sessionId igual ao valor informado.

filter[primarySession][eq]
boolean

Filtra por primarySession igual ao valor informado.

filter[createdAt][gte]
string format: date-time

Filtra por createdAt maior ou igual ao valor informado.

filter[createdAt][lte]
string format: date-time

Filtra por createdAt menor ou igual ao valor informado.

filter[updatedAt][gte]
string format: date-time

Filtra por updatedAt maior ou igual ao valor informado.

filter[updatedAt][lte]
string format: date-time

Filtra por updatedAt menor ou igual ao valor informado.

limit
integer format: int32
default: 25 >= 1 <= 100

Itens por página. 1 a 100; padrão 25.

cursor
string

Cursor opaco da próxima página, devolvido em nextCursor da resposta anterior. Omita na primeira página.

sort
string

Campo de ordenação: id, createdAt (padrão -id). Prefixe com - para descendente (ex.: sort=-createdAt); sempre desempatado por id na mesma direção.

Exemplo
-createdAt
fields
string

Campos de primeiro nível a retornar, separados por vírgula (id sempre volta): id, sessionId, sessionNumber, sessionUrl, channelLabel, contactName, linkOrigin, primarySession, lastNoteStatus, lastNoteAt, linkedByAgentId, alsoLinkedToTicketId, createdAt, updatedAt.

Exemplo
id,sessionId,sessionNumber
expand
string

Objetos a acrescentar à resposta, separados por vírgula, até 3 por requisição: . Sem o escopo exigido de algum item pedido: 403 insufficient_scope.

Exemplo
customer,agent

Respostas

Seção intitulada “Responses”

200

Seção intitulada “200”

Página de conversas vinculadas

Media typeapplication/json
object
data
Array<object>

Conversa do MSP Talks vinculada a um ticket.

object
alsoLinkedToTicketId

Outro ticket da mesma empresa que já usa esta conversa. Só vem preenchido na resposta de POST /chat-sessions, e é aviso, não erro: a mesma conversa pode estar em mais de um ticket. Nas demais respostas — inclusive a de iniciar conversa, que também cria um vínculo — vem sempre nulo, porque a conversa é nova e não havia o que comparar.

integer format: int64
nullable
channelLabel

Canal por onde a conversa acontece, como o catálogo do MSP Talks o nomeia. Decorativo: nulo não impede nada.

string
nullable
contactName

Quem está do outro lado da conversa.

string
nullable
createdAt

Instante em que a conversa foi vinculada ao ticket.

string format: date-time
nullable
id

ID do vínculo entre a conversa e o ticket. É o id da rota.

integer format: int64
lastNoteAt

Instante da última anotação enviada à conversa. Nulo quando nenhuma foi tentada.

string format: date-time
nullable
lastNoteStatus

Resultado da última anotação enviada à conversa: NONE, SENT ou FAILED.

string
nullable
linkOrigin

De onde veio o vínculo: MANUAL (alguém apontou a conversa), OUTBOUND (o Desk abriu a conversa), WEBHOOK (a conversa originou o ticket) ou EMBED (o ticket foi aberto de dentro da conversa).

string
nullable
linkedByAgentId

Agente que vinculou a conversa. Nulo no vínculo automático, que não tem pessoa por trás.

integer format: int64
nullable
primarySession

Se esta é a conversa principal do ticket — a que o ticket referencia. No máximo uma por ticket.

boolean
nullable
sessionId

ID da conversa no MSP Talks.

string
nullable
sessionNumber

Protocolo da conversa no MSP Talks.

string
nullable
sessionUrl

Endereço da conversa no MSP Talks. Nulo quando não foi possível derivar o domínio da instalação do cliente.

string
nullable
updatedAt

Igual a lastNoteAt quando há anotação, e a createdAt quando não há: a anotação é a única alteração que o vínculo sofre.

string format: date-time
nullable
nextCursor

Cursor opaco da próxima página; null quando não há mais páginas.

string
nullable
Exemplo
{
  "data": [
    {
      "alsoLinkedToTicketId": null,
      "channelLabel": "Suporte WhatsApp",
      "contactName": "Beatriz Lima",
      "createdAt": "2026-01-10T12:50:00Z",
      "id": 77,
      "lastNoteAt": "2026-01-10T14:10:00Z",
      "lastNoteStatus": "SENT",
      "linkOrigin": "OUTBOUND",
      "linkedByAgentId": 42,
      "primarySession": true,
      "sessionId": "3b2f6c1e-9a4d-4f8b-8c2e-1d5a7e9b0c34",
      "sessionNumber": "98765",
      "sessionUrl": "https://atendimento.exemplo.com.br/sessions/3b2f6c1e-9a4d-4f8b-8c2e-1d5a7e9b0c34",
      "updatedAt": "2026-01-10T14:10:00Z"
    }
  ],
  "nextCursor": "eyJpZCI6MTA0Mn0"
}

Cabeçalhos

Seção intitulada “Headers”
RateLimit-Limit
integer format: int32

Capacidade do balde mais restritivo consumido nesta requisição

RateLimit-Remaining
integer format: int32

Requisições restantes nesse balde

RateLimit-Reset
integer format: int32

Segundos até o balde encher de novo

400

Seção intitulada “400”

Requisição malformada ou parâmetros de consulta inválidos

Media typeapplication/problem+json

Erro no formato RFC 9457 (application/problem+json).

object
code
required

Código estável do erro, para tratamento programático.

string
detail
required

Explicação legível deste erro específico.

string
errors

Erros de campo — presente quando a falha vem de validação de campo.

Array<object>
object
code

Código estável do erro de campo.

string
Allowed values: required too_long too_short invalid_value invalid_format unknown_field unsupported_operator unsupported_field out_of_range not_found inactive inconsistent_reference not_applicable
field

Campo com erro, em notação de ponto/colchete. Ausente quando o erro não é de um campo específico.

string
nullable
message

Mensagem traduzida no locale da requisição.

string
layer

Presente só no 429

string
Allowed values: ip company key operation concurrency
operation

Presente só quando layer=operation

string
Allowed values: report pdf upload
requestId

Identificador da requisição — informe-o ao suporte ao reportar um erro.

string
requiredScope

Presente só no 403 insufficient_scope

string
status
required

Status HTTP da resposta.

integer format: int32
title
required

Título curto e legível do erro.

string
type
required

URI que identifica o tipo do erro.

string
Exemplo
{
  "code": "not_found",
  "detail": "O recurso solicitado não foi encontrado.",
  "errors": [
    {
      "code": "required"
    }
  ],
  "layer": "ip",
  "operation": "report",
  "requestId": "7f3a9c2e-4b1d-4f7a-9e0c-2b8d6a1f3c55",
  "status": 404,
  "title": "Recurso não encontrado",
  "type": "https://developers.mspdesk.com.br/erros/#not_found"
}

Cabeçalhos

Seção intitulada “Headers”
RateLimit-Limit
integer format: int32

Capacidade do balde mais restritivo consumido nesta requisição

RateLimit-Remaining
integer format: int32

Requisições restantes nesse balde

RateLimit-Reset
integer format: int32

Segundos até o balde encher de novo

401

Seção intitulada “401”

Chave de API ausente, inválida, revogada ou expirada

Media typeapplication/problem+json

Erro no formato RFC 9457 (application/problem+json).

object
code
required

Código estável do erro, para tratamento programático.

string
detail
required

Explicação legível deste erro específico.

string
errors

Erros de campo — presente quando a falha vem de validação de campo.

Array<object>
object
code

Código estável do erro de campo.

string
Allowed values: required too_long too_short invalid_value invalid_format unknown_field unsupported_operator unsupported_field out_of_range not_found inactive inconsistent_reference not_applicable
field

Campo com erro, em notação de ponto/colchete. Ausente quando o erro não é de um campo específico.

string
nullable
message

Mensagem traduzida no locale da requisição.

string
layer

Presente só no 429

string
Allowed values: ip company key operation concurrency
operation

Presente só quando layer=operation

string
Allowed values: report pdf upload
requestId

Identificador da requisição — informe-o ao suporte ao reportar um erro.

string
requiredScope

Presente só no 403 insufficient_scope

string
status
required

Status HTTP da resposta.

integer format: int32
title
required

Título curto e legível do erro.

string
type
required

URI que identifica o tipo do erro.

string
Exemplo
{
  "code": "not_found",
  "detail": "O recurso solicitado não foi encontrado.",
  "errors": [
    {
      "code": "required"
    }
  ],
  "layer": "ip",
  "operation": "report",
  "requestId": "7f3a9c2e-4b1d-4f7a-9e0c-2b8d6a1f3c55",
  "status": 404,
  "title": "Recurso não encontrado",
  "type": "https://developers.mspdesk.com.br/erros/#not_found"
}

403

Seção intitulada “403”

Acesso negado: empresa inativa (account_inactive), API pública desabilitada para a empresa (public_api_disabled), escopo liberado só com a API pública (scope_requires_public_api) ou escopo insuficiente (insufficient_scope)

Media typeapplication/problem+json

Erro no formato RFC 9457 (application/problem+json).

object
code
required

Código estável do erro, para tratamento programático.

string
detail
required

Explicação legível deste erro específico.

string
errors

Erros de campo — presente quando a falha vem de validação de campo.

Array<object>
object
code

Código estável do erro de campo.

string
Allowed values: required too_long too_short invalid_value invalid_format unknown_field unsupported_operator unsupported_field out_of_range not_found inactive inconsistent_reference not_applicable
field

Campo com erro, em notação de ponto/colchete. Ausente quando o erro não é de um campo específico.

string
nullable
message

Mensagem traduzida no locale da requisição.

string
layer

Presente só no 429

string
Allowed values: ip company key operation concurrency
operation

Presente só quando layer=operation

string
Allowed values: report pdf upload
requestId

Identificador da requisição — informe-o ao suporte ao reportar um erro.

string
requiredScope

Presente só no 403 insufficient_scope

string
status
required

Status HTTP da resposta.

integer format: int32
title
required

Título curto e legível do erro.

string
type
required

URI que identifica o tipo do erro.

string
Exemplo
{
  "code": "not_found",
  "detail": "O recurso solicitado não foi encontrado.",
  "errors": [
    {
      "code": "required"
    }
  ],
  "layer": "ip",
  "operation": "report",
  "requestId": "7f3a9c2e-4b1d-4f7a-9e0c-2b8d6a1f3c55",
  "status": 404,
  "title": "Recurso não encontrado",
  "type": "https://developers.mspdesk.com.br/erros/#not_found"
}

Cabeçalhos

Seção intitulada “Headers”
RateLimit-Limit
integer format: int32

Capacidade do balde mais restritivo consumido nesta requisição

RateLimit-Remaining
integer format: int32

Requisições restantes nesse balde

RateLimit-Reset
integer format: int32

Segundos até o balde encher de novo

404

Seção intitulada “404”

Recurso inexistente, de outra empresa, ou rota inexistente

Media typeapplication/problem+json

Erro no formato RFC 9457 (application/problem+json).

object
code
required

Código estável do erro, para tratamento programático.

string
detail
required

Explicação legível deste erro específico.

string
errors

Erros de campo — presente quando a falha vem de validação de campo.

Array<object>
object
code

Código estável do erro de campo.

string
Allowed values: required too_long too_short invalid_value invalid_format unknown_field unsupported_operator unsupported_field out_of_range not_found inactive inconsistent_reference not_applicable
field

Campo com erro, em notação de ponto/colchete. Ausente quando o erro não é de um campo específico.

string
nullable
message

Mensagem traduzida no locale da requisição.

string
layer

Presente só no 429

string
Allowed values: ip company key operation concurrency
operation

Presente só quando layer=operation

string
Allowed values: report pdf upload
requestId

Identificador da requisição — informe-o ao suporte ao reportar um erro.

string
requiredScope

Presente só no 403 insufficient_scope

string
status
required

Status HTTP da resposta.

integer format: int32
title
required

Título curto e legível do erro.

string
type
required

URI que identifica o tipo do erro.

string
Exemplo
{
  "code": "not_found",
  "detail": "O recurso solicitado não foi encontrado.",
  "errors": [
    {
      "code": "required"
    }
  ],
  "layer": "ip",
  "operation": "report",
  "requestId": "7f3a9c2e-4b1d-4f7a-9e0c-2b8d6a1f3c55",
  "status": 404,
  "title": "Recurso não encontrado",
  "type": "https://developers.mspdesk.com.br/erros/#not_found"
}

Cabeçalhos

Seção intitulada “Headers”
RateLimit-Limit
integer format: int32

Capacidade do balde mais restritivo consumido nesta requisição

RateLimit-Remaining
integer format: int32

Requisições restantes nesse balde

RateLimit-Reset
integer format: int32

Segundos até o balde encher de novo

429

Seção intitulada “429”

Limite de uso atingido (rate_limited); o campo layer indica a camada: ip, company, key, operation ou concurrency

Media typeapplication/problem+json

Erro no formato RFC 9457 (application/problem+json).

object
code
required

Código estável do erro, para tratamento programático.

string
detail
required

Explicação legível deste erro específico.

string
errors

Erros de campo — presente quando a falha vem de validação de campo.

Array<object>
object
code

Código estável do erro de campo.

string
Allowed values: required too_long too_short invalid_value invalid_format unknown_field unsupported_operator unsupported_field out_of_range not_found inactive inconsistent_reference not_applicable
field

Campo com erro, em notação de ponto/colchete. Ausente quando o erro não é de um campo específico.

string
nullable
message

Mensagem traduzida no locale da requisição.

string
layer

Presente só no 429

string
Allowed values: ip company key operation concurrency
operation

Presente só quando layer=operation

string
Allowed values: report pdf upload
requestId

Identificador da requisição — informe-o ao suporte ao reportar um erro.

string
requiredScope

Presente só no 403 insufficient_scope

string
status
required

Status HTTP da resposta.

integer format: int32
title
required

Título curto e legível do erro.

string
type
required

URI que identifica o tipo do erro.

string
Exemplo
{
  "code": "not_found",
  "detail": "O recurso solicitado não foi encontrado.",
  "errors": [
    {
      "code": "required"
    }
  ],
  "layer": "ip",
  "operation": "report",
  "requestId": "7f3a9c2e-4b1d-4f7a-9e0c-2b8d6a1f3c55",
  "status": 404,
  "title": "Recurso não encontrado",
  "type": "https://developers.mspdesk.com.br/erros/#not_found"
}

Cabeçalhos

Seção intitulada “Headers”
RateLimit-Limit
integer format: int32

Capacidade do balde mais restritivo consumido nesta requisição

RateLimit-Remaining
integer format: int32

Requisições restantes nesse balde

RateLimit-Reset
integer format: int32

Segundos até o balde encher de novo

Retry-After
integer format: int32

Segundos até poder repetir

500

Seção intitulada “500”

Erro interno inesperado

Media typeapplication/problem+json

Erro no formato RFC 9457 (application/problem+json).

object
code
required

Código estável do erro, para tratamento programático.

string
detail
required

Explicação legível deste erro específico.

string
errors

Erros de campo — presente quando a falha vem de validação de campo.

Array<object>
object
code

Código estável do erro de campo.

string
Allowed values: required too_long too_short invalid_value invalid_format unknown_field unsupported_operator unsupported_field out_of_range not_found inactive inconsistent_reference not_applicable
field

Campo com erro, em notação de ponto/colchete. Ausente quando o erro não é de um campo específico.

string
nullable
message

Mensagem traduzida no locale da requisição.

string
layer

Presente só no 429

string
Allowed values: ip company key operation concurrency
operation

Presente só quando layer=operation

string
Allowed values: report pdf upload
requestId

Identificador da requisição — informe-o ao suporte ao reportar um erro.

string
requiredScope

Presente só no 403 insufficient_scope

string
status
required

Status HTTP da resposta.

integer format: int32
title
required

Título curto e legível do erro.

string
type
required

URI que identifica o tipo do erro.

string
Exemplo
{
  "code": "not_found",
  "detail": "O recurso solicitado não foi encontrado.",
  "errors": [
    {
      "code": "required"
    }
  ],
  "layer": "ip",
  "operation": "report",
  "requestId": "7f3a9c2e-4b1d-4f7a-9e0c-2b8d6a1f3c55",
  "status": 404,
  "title": "Recurso não encontrado",
  "type": "https://developers.mspdesk.com.br/erros/#not_found"
}

Cabeçalhos

Seção intitulada “Headers”
RateLimit-Limit
integer format: int32

Capacidade do balde mais restritivo consumido nesta requisição

RateLimit-Remaining
integer format: int32

Requisições restantes nesse balde

RateLimit-Reset
integer format: int32

Segundos até o balde encher de novo