Principal APIs Como atualizar atributos customizados em conversas via API

Como atualizar atributos customizados em conversas via API

Última atualização em May 21, 2026

Quando usar

  • Você precisa atualizar atributos customizados (Categoria, Motivo, Tier, etc.) de uma conversa via API
  • Você está integrando com outro sistema que precisa enviar metadata para a conversa do Cloud Chat
  • Você quer remover atributos específicos sem afetar os demais

Pré-requisitos

CONVERSATION_ID vs display_id — este endpoint usa o display_id (o número visível na interface do Cloud Chat) como identificador da conversa na URL, não o ID interno.

Endpoint

PUT https://cloudchat.cloudhumans.com/api/v1/accounts/{ACCOUNT_ID}/conversations/{CONVERSATION_ID}/custom_attributes

Headers

Header Valor
content-type application/json
api_access_token Seu token de API

Corpo da requisição

A requisição deve conter um único campo, custom_attributes, com os atributos a atualizar:

{
  "custom_attributes": {
    "to_be_updated": "new_value",
    "to_be_removed": null
  }
}

O conversation_id da conversa não vai no body — ele é passado como parâmetro na URL.

Exemplo de requisição

curl --request PUT \
  --url 'https://cloudchat.cloudhumans.com/api/v1/accounts/ACCOUNT_ID/conversations/CONVERSATION_ID/custom_attributes' \
  --header 'api_access_token: API_TOKEN' \
  --header 'content-type: application/json' \
  --data '{
    "custom_attributes": {
      "to_be_updated": "new_value",
      "to_be_removed": null
    }
  }'

Tipos de atributos suportados

Os atributos customizados têm um tipo definido na configuração — respeite o tipo ao atualizar via API.

Tipo Requisitos
Texto Valor String
Número Apenas dígitos. Não pode conter caracteres alfabéticos ou especiais
Link URL válida (http/https) que termina em domínio válido (.com, .net, etc.)
Data Formato ISO 8601 (YYYY-MM-DDTHH:MM:SS.sssZ). Ex: "2025-01-01T12:00:00.000Z"
Lista String que deve estar presente na lista de opções definidas no atributo
Multi-list Array de strings. Cada valor deve existir nas opções pré-definidas. Ex: ["opção1","opção2"]
Checkbox "true"/"false" (string) ou true/false (booleano)

Como remover um atributo

Para remover um valor atribuído a um atributo customizado, envie null ou string vazia (""). O sistema remove o atributo do objeto custom_attributes.

Tratamento de erros

Erro Código Significado
Conversation not found 404 A conversa não foi encontrada
Invalid attributes 422 Body incorreto
Atributo inexistente — O atributo não está cadastrado na conta
Tipo errado — Mensagens como "number_attr must contain only numeric digits" ou "date_attr must be in ISO8601 format"

Cuidado: PUT (merge) vs POST (replace)

Existem dois endpoints para alterar custom attributes — escolha o correto:

Método Comportamento Quando usar
PUT .../custom_attributes (este) Merge: atualiza os campos enviados e preserva os demais Recomendado para a maioria dos casos
POST .../conversations/{ID}/custom_attributes Replace: substitui todos os custom attributes pelo objeto enviado Use com cuidado — campos não enviados são apagados

Sempre prefira PUT para evitar perda de dados acidental.

Observações