Inicia uma conversa no MSP Talks a partir do ticket
curl --request POST \ --url https://public-api.mspdesk.com.br/v1/tickets/1/chat-conversations \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "agentId": 42, "channelId": "c1", "departmentId": "d1", "parameters": { "CHAMADO": "18342", "NOME": "Beatriz" }, "primary": true, "templateId": "t1" }'Escopo exigido: tickets:write. Manda o modelo aprovado pelo canal para o contato do ticket — o telefone sai do contato, no servidor, e não do corpo: um número livre transformaria permissão de ticket em permissão de mandar mensagem para qualquer um.
Isto custa dinheiro: a Meta cobra por conversa iniciada. Mande Idempotency-Key — uma repetição por timeout devolve a resposta original, inclusive o 202, em vez de iniciar uma segunda conversa.
Duas respostas possíveis, e as duas são sucesso:
201com o vínculo e o cabeçalhoLocation, quando a conversa já existe do outro lado;202sem corpo, quando não há vínculo a devolver: a conversa ainda não nasceu do outro lado, o vínculo falhou depois do envio, ou a chamada ao MSP Talks ficou sem resposta depois de a conexão abrir (timeout). O202significa “pode ter saído”, e é assim que ele deve ser lido: preferimos aceitar uma mensagem que talvez não tenha saído a cobrar o cliente duas vezes.
Como conferir depois de um 202, sempre: liste as conversas do ticket (GET /v1/tickets/{ticketId}/chat-sessions). Se a conversa aparecer, a mensagem saiu — não reenvie. Se nada aparecer ali depois de alguns minutos (a conversa também entra sozinha quando o contato responder), então o envio provavelmente não aconteceu: para tentar de novo, mande a requisição com uma Idempotency-Key NOVA. Repetir com a mesma chave devolve o 202 guardado e não fala com o fornecedor.
Os erros desta rota significam que nenhuma mensagem saiu: 422 é recusa nossa, antes de qualquer envio, e 503 é recusa explícita do MSP Talks ou conexão que nem chegou a abrir (recusada, endereço que não resolve). Os dois podem ser repetidos com a mesma chave.
agentId é obrigatório: é o e-mail dele que o MSP Talks recebe como atendente da conversa. O ticket precisa ter contato com telefone, e a integração precisa estar configurada e ativa na empresa.
Autorizações
Seção intitulada “Authorizations”Parâmetros
Seção intitulada “Parameters”Parâmetros de caminho
Seção intitulada “Path Parameters”ID do ticket
Exemplo
1Parâmetros de cabeçalho
Seção intitulada “Header Parameters”Garante que repetir a mesma requisição não duplique o efeito. 1 a 255 caracteres ASCII visíveis. Repetir a mesma chave devolve a mesma resposta (cabeçalho Idempotent-Replayed: true); a mesma chave com um corpo diferente é 422 idempotency_key_reused. A resposta repetida é a original: o corpo mantém o requestId e o idioma da primeira requisição; o cabeçalho X-Request-Id é o da requisição nova. A repetição também consome o limite de uso.
Corpo da requisiçãorequired
Seção intitulada “Request Bodyrequired”Conversa a iniciar no MSP Talks a partir do ticket.
object
Agente que fica registrado como quem abriu a conversa. Precisa existir, estar ativo e ser da empresa da chave — é o e-mail dele que o MSP Talks recebe como atendente.
Canal por onde falar, entre os da conta do MSP Talks da empresa.
Equipe a quem atribuir a conversa. Opcional.
Valor final de cada parâmetro do modelo.
object
Valor final de cada parâmetro do modelo.
Se a conversa aberta vira a principal do ticket. Ausente decide sozinho.
Modelo aprovado no canal. É ele que define o texto que o cliente recebe.
Exemplo
{ "agentId": 42, "channelId": "c1", "departmentId": "d1", "parameters": { "CHAMADO": "18342", "NOME": "Beatriz" }, "primary": true, "templateId": "t1"}Respostas
Seção intitulada “Responses”A conversa foi aberta e vinculada
Conversa do MSP Talks vinculada a um ticket.
object
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.
Canal por onde a conversa acontece, como o catálogo do MSP Talks o nomeia. Decorativo: nulo não impede nada.
Quem está do outro lado da conversa.
Instante em que a conversa foi vinculada ao ticket.
ID do vínculo entre a conversa e o ticket. É o id da rota.
Instante da última anotação enviada à conversa. Nulo quando nenhuma foi tentada.
Resultado da última anotação enviada à conversa: NONE, SENT ou FAILED.
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).
Agente que vinculou a conversa. Nulo no vínculo automático, que não tem pessoa por trás.
Se esta é a conversa principal do ticket — a que o ticket referencia. No máximo uma por ticket.
ID da conversa no MSP Talks.
Protocolo da conversa no MSP Talks.
Endereço da conversa no MSP Talks. Nulo quando não foi possível derivar o domínio da instalação do cliente.
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.
Exemplo
{ "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"}Cabeçalhos
Seção intitulada “Headers”Capacidade do balde mais restritivo consumido nesta requisição
Requisições restantes nesse balde
Segundos até o balde encher de novo
A mensagem pode ter saído e não há vínculo a devolver. Confirme listando as conversas do ticket em GET /v1/tickets/{ticketId}/chat-sessions: se a conversa aparecer, não reenvie; se nada aparecer ali, tente de novo com uma Idempotency-Key NOVA — repetir com a mesma devolve este mesmo 202 sem falar com o fornecedor
Conversa do MSP Talks vinculada a um ticket.
object
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.
Canal por onde a conversa acontece, como o catálogo do MSP Talks o nomeia. Decorativo: nulo não impede nada.
Quem está do outro lado da conversa.
Instante em que a conversa foi vinculada ao ticket.
ID do vínculo entre a conversa e o ticket. É o id da rota.
Instante da última anotação enviada à conversa. Nulo quando nenhuma foi tentada.
Resultado da última anotação enviada à conversa: NONE, SENT ou FAILED.
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).
Agente que vinculou a conversa. Nulo no vínculo automático, que não tem pessoa por trás.
Se esta é a conversa principal do ticket — a que o ticket referencia. No máximo uma por ticket.
ID da conversa no MSP Talks.
Protocolo da conversa no MSP Talks.
Endereço da conversa no MSP Talks. Nulo quando não foi possível derivar o domínio da instalação do cliente.
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.
Exemplo
{ "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"}Cabeçalhos
Seção intitulada “Headers”Capacidade do balde mais restritivo consumido nesta requisição
Requisições restantes nesse balde
Segundos até o balde encher de novo
Requisição malformada ou parâmetros de consulta inválidos
Erro no formato RFC 9457 (application/problem+json).
object
Código estável do erro, para tratamento programático.
Explicação legível deste erro específico.
Erros de campo — presente quando a falha vem de validação de campo.
object
Código estável do erro de campo.
Campo com erro, em notação de ponto/colchete. Ausente quando o erro não é de um campo específico.
Mensagem traduzida no locale da requisição.
Presente só no 429
Presente só quando layer=operation
Identificador da requisição — informe-o ao suporte ao reportar um erro.
Presente só no 403 insufficient_scope
Status HTTP da resposta.
Título curto e legível do erro.
URI que identifica o tipo do erro.
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”Capacidade do balde mais restritivo consumido nesta requisição
Requisições restantes nesse balde
Segundos até o balde encher de novo
Chave de API ausente, inválida, revogada ou expirada
Erro no formato RFC 9457 (application/problem+json).
object
Código estável do erro, para tratamento programático.
Explicação legível deste erro específico.
Erros de campo — presente quando a falha vem de validação de campo.
object
Código estável do erro de campo.
Campo com erro, em notação de ponto/colchete. Ausente quando o erro não é de um campo específico.
Mensagem traduzida no locale da requisição.
Presente só no 429
Presente só quando layer=operation
Identificador da requisição — informe-o ao suporte ao reportar um erro.
Presente só no 403 insufficient_scope
Status HTTP da resposta.
Título curto e legível do erro.
URI que identifica o tipo do erro.
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"}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)
Erro no formato RFC 9457 (application/problem+json).
object
Código estável do erro, para tratamento programático.
Explicação legível deste erro específico.
Erros de campo — presente quando a falha vem de validação de campo.
object
Código estável do erro de campo.
Campo com erro, em notação de ponto/colchete. Ausente quando o erro não é de um campo específico.
Mensagem traduzida no locale da requisição.
Presente só no 429
Presente só quando layer=operation
Identificador da requisição — informe-o ao suporte ao reportar um erro.
Presente só no 403 insufficient_scope
Status HTTP da resposta.
Título curto e legível do erro.
URI que identifica o tipo do erro.
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”Capacidade do balde mais restritivo consumido nesta requisição
Requisições restantes nesse balde
Segundos até o balde encher de novo
not_found: o ticket ou o agente não existe nesta empresa
Erro no formato RFC 9457 (application/problem+json).
object
Código estável do erro, para tratamento programático.
Explicação legível deste erro específico.
Erros de campo — presente quando a falha vem de validação de campo.
object
Código estável do erro de campo.
Campo com erro, em notação de ponto/colchete. Ausente quando o erro não é de um campo específico.
Mensagem traduzida no locale da requisição.
Presente só no 429
Presente só quando layer=operation
Identificador da requisição — informe-o ao suporte ao reportar um erro.
Presente só no 403 insufficient_scope
Status HTTP da resposta.
Título curto e legível do erro.
URI que identifica o tipo do erro.
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”Capacidade do balde mais restritivo consumido nesta requisição
Requisições restantes nesse balde
Segundos até o balde encher de novo
Conflito — unicidade, recurso em uso, ou Idempotency-Key em execução
Erro no formato RFC 9457 (application/problem+json).
object
Código estável do erro, para tratamento programático.
Explicação legível deste erro específico.
Erros de campo — presente quando a falha vem de validação de campo.
object
Código estável do erro de campo.
Campo com erro, em notação de ponto/colchete. Ausente quando o erro não é de um campo específico.
Mensagem traduzida no locale da requisição.
Presente só no 429
Presente só quando layer=operation
Identificador da requisição — informe-o ao suporte ao reportar um erro.
Presente só no 403 insufficient_scope
Status HTTP da resposta.
Título curto e legível do erro.
URI que identifica o tipo do erro.
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”Capacidade do balde mais restritivo consumido nesta requisição
Requisições restantes nesse balde
Segundos até o balde encher de novo
Corpo da requisição acima de 1 MB
Erro no formato RFC 9457 (application/problem+json).
object
Código estável do erro, para tratamento programático.
Explicação legível deste erro específico.
Erros de campo — presente quando a falha vem de validação de campo.
object
Código estável do erro de campo.
Campo com erro, em notação de ponto/colchete. Ausente quando o erro não é de um campo específico.
Mensagem traduzida no locale da requisição.
Presente só no 429
Presente só quando layer=operation
Identificador da requisição — informe-o ao suporte ao reportar um erro.
Presente só no 403 insufficient_scope
Status HTTP da resposta.
Título curto e legível do erro.
URI que identifica o tipo do erro.
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”Capacidade do balde mais restritivo consumido nesta requisição
Requisições restantes nesse balde
Segundos até o balde encher de novo
Content-Type não suportado
Erro no formato RFC 9457 (application/problem+json).
object
Código estável do erro, para tratamento programático.
Explicação legível deste erro específico.
Erros de campo — presente quando a falha vem de validação de campo.
object
Código estável do erro de campo.
Campo com erro, em notação de ponto/colchete. Ausente quando o erro não é de um campo específico.
Mensagem traduzida no locale da requisição.
Presente só no 429
Presente só quando layer=operation
Identificador da requisição — informe-o ao suporte ao reportar um erro.
Presente só no 403 insufficient_scope
Status HTTP da resposta.
Título curto e legível do erro.
URI que identifica o tipo do erro.
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”Capacidade do balde mais restritivo consumido nesta requisição
Requisições restantes nesse balde
Segundos até o balde encher de novo
ticket_deleted em ticket na lixeira, ou business_rule_violation quando o contato do ticket não tem telefone, ou quando a integração com o MSP Talks não está configurada/ativa nesta empresa. Nenhuma mensagem saiu
Erro no formato RFC 9457 (application/problem+json).
object
Código estável do erro, para tratamento programático.
Explicação legível deste erro específico.
Erros de campo — presente quando a falha vem de validação de campo.
object
Código estável do erro de campo.
Campo com erro, em notação de ponto/colchete. Ausente quando o erro não é de um campo específico.
Mensagem traduzida no locale da requisição.
Presente só no 429
Presente só quando layer=operation
Identificador da requisição — informe-o ao suporte ao reportar um erro.
Presente só no 403 insufficient_scope
Status HTTP da resposta.
Título curto e legível do erro.
URI que identifica o tipo do erro.
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”Capacidade do balde mais restritivo consumido nesta requisição
Requisições restantes nesse balde
Segundos até o balde encher de novo
Limite de uso atingido (rate_limited); o campo layer indica a camada: ip, company, key, operation ou concurrency
Erro no formato RFC 9457 (application/problem+json).
object
Código estável do erro, para tratamento programático.
Explicação legível deste erro específico.
Erros de campo — presente quando a falha vem de validação de campo.
object
Código estável do erro de campo.
Campo com erro, em notação de ponto/colchete. Ausente quando o erro não é de um campo específico.
Mensagem traduzida no locale da requisição.
Presente só no 429
Presente só quando layer=operation
Identificador da requisição — informe-o ao suporte ao reportar um erro.
Presente só no 403 insufficient_scope
Status HTTP da resposta.
Título curto e legível do erro.
URI que identifica o tipo do erro.
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”Capacidade do balde mais restritivo consumido nesta requisição
Requisições restantes nesse balde
Segundos até o balde encher de novo
Segundos até poder repetir
Erro interno inesperado
Erro no formato RFC 9457 (application/problem+json).
object
Código estável do erro, para tratamento programático.
Explicação legível deste erro específico.
Erros de campo — presente quando a falha vem de validação de campo.
object
Código estável do erro de campo.
Campo com erro, em notação de ponto/colchete. Ausente quando o erro não é de um campo específico.
Mensagem traduzida no locale da requisição.
Presente só no 429
Presente só quando layer=operation
Identificador da requisição — informe-o ao suporte ao reportar um erro.
Presente só no 403 insufficient_scope
Status HTTP da resposta.
Título curto e legível do erro.
URI que identifica o tipo do erro.
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”Capacidade do balde mais restritivo consumido nesta requisição
Requisições restantes nesse balde
Segundos até o balde encher de novo
service_unavailable: o MSP Talks recusou a chamada respondendo um erro, ou a conexão com ele nem chegou a abrir — nenhuma mensagem saiu, e vale repetir, inclusive com a mesma Idempotency-Key. Uma falha SEM resposta depois de a conexão abrir não chega aqui: ela sai como 202, porque não dá para afirmar que nada foi enviado. O mesmo código também sai como idempotency_unavailable quando a requisição traz Idempotency-Key e o Redis está fora — o campo code do corpo distingue os dois
Erro no formato RFC 9457 (application/problem+json).
object
Código estável do erro, para tratamento programático.
Explicação legível deste erro específico.
Erros de campo — presente quando a falha vem de validação de campo.
object
Código estável do erro de campo.
Campo com erro, em notação de ponto/colchete. Ausente quando o erro não é de um campo específico.
Mensagem traduzida no locale da requisição.
Presente só no 429
Presente só quando layer=operation
Identificador da requisição — informe-o ao suporte ao reportar um erro.
Presente só no 403 insufficient_scope
Status HTTP da resposta.
Título curto e legível do erro.
URI que identifica o tipo do erro.
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”Capacidade do balde mais restritivo consumido nesta requisição
Requisições restantes nesse balde
Segundos até o balde encher de novo