Responde ao contato do ticket
curl --request POST \ --url https://public-api.mspdesk.com.br/v1/tickets/1/notes/reply \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "agentId": 42, "attachmentIds": [ 912 ], "body": "<p>Olá, Beatriz. Reiniciamos o spooler de impressão e a impressora voltou a responder.</p>", "cc": [ "financeiro@acme.com.br" ] }'Escopo exigido: tickets:write. Envia um e-mail ao contato do ticket e registra a resposta na linha do tempo. O destinatário não vem no corpo: é sempre o contato do ticket, como na tela — cc são só as cópias, no máximo 20 e sem repetições. Por isso a resposta é sempre pública e não há visibility a informar.
Um ticket sem contato solicitante responde 422 business_rule_violation: não há para quem enviar.
Informe exatamente um entre body e messageTemplateId. Com messageTemplateId, o corpo é o texto do modelo já resolvido para este ticket — e os arquivos do modelo não são anexados; para anexar, envie o arquivo em POST /v1/tickets/{ticketId}/attachments e passe o id em attachmentIds.
then decide o que acontece com o ticket depois da resposta: PAUSE deixa o atendimento pendente e COMPLETE conclui. A resposta é sempre a nota criada — o novo estado do ticket sai em GET /v1/tickets/{id}. Com COMPLETE, as condições da conclusão (tarefa em aberto, vínculo dependente em aberto, apontamento sem descrição, campo obrigatório para concluir) são conferidas antes de gravar: se alguma impede, a resposta é 422 business_rule_violation, nada é gravado e nenhum e-mail sai — resolva o impedimento e reenvie. Se a conclusão ainda for recusada depois (o ticket mudou entre a conferência e a conclusão), a resposta também é 422 business_rule_violation, mas a resposta ao contato já ficou gravada e o e-mail sai: não a reenvie — conclua o ticket pela ação de conclusão.
Nenhum parâmetro de consulta é aceito.
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”Resposta a enviar ao contato do ticket.
object
Agente que assina a resposta. Opcional: sem ele a resposta fica sem autor humano.
Identificadores de anexos já enviados ao ticket que devem seguir no e-mail. Suba o arquivo antes em POST /v1/tickets/{ticketId}/attachments. Máximo de 20; um id repetido conta uma vez só. Cada id precisa ser um anexo deste ticket ainda sem nota nem apontamento: id que não está na lista de anexos do ticket responde 404 not_found e anexo já vinculado responde 422 invalid_value, os dois em attachmentIds[i] e sem gravar nada.
Texto da resposta, em HTML. Alternativo a messageTemplateId: informe exatamente um dos dois.
Endereços em cópia. O destinatário principal é sempre o contato do ticket e não entra aqui. Máximo de 20, sem repetições nem elementos vazios. Juntos, separados por ; , cabem em 4000 caracteres; acima disso a resposta é 422 com too_long.
Modelo de mensagem a aplicar ao ticket; o texto resolvido vira o corpo da resposta. Alternativo a body.
Efeito da nota sobre o ticket.
Exemplo
{ "agentId": 42, "attachmentIds": [ 912 ], "body": "<p>Olá, Beatriz. Reiniciamos o spooler de impressão e a impressora voltou a responder.</p>", "cc": [ "financeiro@acme.com.br" ]}Respostas
Seção intitulada “Responses”A resposta registrada
Nota, resposta ou encaminhamento registrado no ticket.
object
Identificador da chave de API que escreveu a nota; nulo quando a nota não veio da API.
Nome atual da chave de API que escreveu a nota; nulo quando a chave não existe mais ou não é desta empresa.
Anexos do ticket vinculados a esta nota.
Agente que assina a nota; nulo nas notas sem autor humano.
Contato que escreveu a nota pelo portal ou por e-mail; nulo nas demais.
Texto da nota, em HTML.
Cópias do e-mail, separadas por ; — preenchido na resposta.
Instante de criação da nota.
Identificador da nota.
Agentes mencionados na nota.
Quem originou a nota: USER (tela), API (integração), CONTACT_CUSTOMER (portal), EMAIL_INBOUND, integrações de monitoramento ou SYSTEM.
Destinatários do e-mail, separados por ; — preenchido em resposta e encaminhamento.
Remetente registrado quando a nota veio de um e-mail recebido.
Tipo da nota: nota simples, resposta ao contato ou encaminhamento.
Instante da última alteração da nota; igual a createdAt enquanto a nota nunca tiver sido editada.
Visibilidade: PUBLIC aparece para o solicitante no portal e no e-mail; PRIVATE fica só para os agentes.
Exemplo
{ "apiKeyId": 8, "apiKeyName": "Integração ERP", "attachmentIds": [ 912 ], "authorAgentId": 42, "authorContactId": null, "body": "<p>Olá, Beatriz. Reiniciamos o spooler de impressão e a impressora voltou a responder.</p>", "cc": "financeiro@acme.com.br", "createdAt": "2026-01-10T14:05:00Z", "id": 1204, "mentionedAgentIds": [], "origin": "API", "recipients": "beatriz.lima@acme.com.br", "sender": null, "type": "REPLY", "updatedAt": "2026-01-10T14:05:00Z", "visibility": "PUBLIC"}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, o agente ou o modelo de mensagem 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
Falha de validação ou regra de negócio
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
idempotency_unavailable: Redis indisponível para avaliar o cabeçalho Idempotency-Key presente na requisiçã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