Tags

As tags de contato são rótulos coloridos e reutilizáveis que descrevem uma pessoa em todas as conversas dela. Esta seção cobre os endpoints para gerenciar o catálogo de tags da organização e para aplicar e remover tags de um contato externo. Para o uso no produto, em Tags do contato e Gerenciar tags, veja Tags de Contato.

Não confunda este recurso com tags que descrevem uma conversa específica nem com tags de campanhas. A ferramenta nativa manage_tags usa tags de contato; manage_conversation_tags aplica o mesmo vocabulário do catálogo à conversa atual, mas grava outra associação. Esta API pública expõe somente o catálogo e as associações de contatos externos.

Todos os endpoints exigem o header Authorization: Bearer pk_.... Quando houver corpo JSON, inclua também Content-Type: application/json.

Base URL: https://api.squados.io/v1

Consulte Autenticação para obter sua chave, e Erros para a referência de códigos.

O modelo ContactTag

Toda tag é representada por:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "lead quente",
  "color": "orange"
}

Campo	Tipo	Descrição
id	uuid	Identificador da tag.
name	string	Nome da tag, único sem diferenciar maiúsculas e minúsculas na organização.
color	string	Uma de: purple, blue, green, orange, red, pink, teal, gray.

Nota

Os endpoints de catálogo (/tags) são usáveis diretamente. Os endpoints por contato (/contacts/{contactId}/tags) precisam do UUID do contato externo (external_contacts.id). A ferramenta nativa do agente recebe esse contato do contexto da conversa; ela não pede o UUID ao modelo.

---

GET /tags

Lista o catálogo de tags da organização, ordenado por nome.

curl -X GET "https://api.squados.io/v1/tags" \
  -H "Authorization: Bearer pk_sua_chave_aqui"

Resposta — 200 OK

{
  "tags": [
    { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "aguardando pagamento", "color": "blue" },
    { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "name": "cliente", "color": "red" },
    { "id": "8a1b2c3d-4e5f-6789-abcd-ef0123456789", "name": "lead quente", "color": "orange" }
  ]
}

---

PATCH /tags/{tagId}

Renomeia e/ou recolora uma tag do catálogo. A mudança vale para todos os contatos que têm a tag.

Parâmetros de caminho

Nome	Tipo	Descrição
tagId	uuid	ID da tag.

Corpo da requisição

Campo	Tipo	Descrição
name	string	Novo nome da tag. Não pode ser vazio nem colidir com outra tag.
color	string	Nova cor: purple, blue, green, orange, red, pink, teal ou gray.

Envie name ou color por chamada. O runtime atual também aceita os dois campos e executa a renomeação antes da troca de cor, mas as duas mudanças não formam uma operação atômica. Se a segunda falhar, a primeira pode já ter sido aplicada. Um objeto vazio ou apenas com campos desconhecidos também recebe 200 sem alterar a tag; não use esse comportamento como validação.

curl -X PATCH "https://api.squados.io/v1/tags/TAG_ID" \
  -H "Authorization: Bearer pk_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{"name": "lead qualificado"}'

Resposta — 200 OK

{
  "success": true,
  "id": "8a1b2c3d-4e5f-6789-abcd-ef0123456789"
}

Erros relevantes: 400 invalid_request se o ID for inválido, o nome for vazio ou a cor não pertencer à paleta; 404 not_found se a tag não existir na sua organização; 409 conflict se já existir outra tag com o nome informado.

Cuidado

No runtime atual, falhas internas na renomeação são devolvidas como 409 e falhas internas na troca de cor como 400. Depois de um erro inesperado, consulte GET /tags antes de decidir se deve repetir a chamada.

---

DELETE /tags/{tagId}

Exclui a tag do catálogo e a remove de todos os contatos que a tinham. Não pode ser desfeito.

Parâmetros de caminho

Nome	Tipo	Descrição
tagId	uuid	ID da tag.

curl -X DELETE "https://api.squados.io/v1/tags/TAG_ID" \
  -H "Authorization: Bearer pk_sua_chave_aqui"

Resposta — 200 OK

{ "success": true }

Erros relevantes: 400 invalid_request se o tagId não for um UUID válido; 404 not_found se a tag não existir na sua organização; 500 internal_error se a exclusão falhar.

---

GET /contacts/{contactId}/tags

Lista as tags aplicadas a um contato externo. A resposta não garante ordenação; ordene por name no cliente quando a apresentação exigir ordem estável.

Parâmetros de caminho

Nome	Tipo	Descrição
contactId	uuid	ID do contato externo.

curl -X GET "https://api.squados.io/v1/contacts/CONTACT_ID/tags" \
  -H "Authorization: Bearer pk_sua_chave_aqui"

Resposta — 200 OK

{
  "tags": [
    { "id": "8a1b2c3d-4e5f-6789-abcd-ef0123456789", "name": "lead quente", "color": "orange" },
    { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "name": "cliente", "color": "red" }
  ]
}

Erros relevantes: 400 invalid_request se o contactId for inválido; 404 not_found se o contato não existir ou não pertencer à sua organização; 500 internal_error se a leitura das associações falhar.

---

POST /contacts/{contactId}/tags

Aplica uma tag ao contato pelo nome. Se a tag ainda não existir no catálogo da organização, ela é criada automaticamente com uma cor determinística derivada do nome. A procura não diferencia maiúsculas e minúsculas: reaplicar o mesmo nome, inclusive com outra capitalização, reutiliza a tag e a cor já armazenadas. A associação também é idempotente e não cria duplicata.

Parâmetros de caminho

Nome	Tipo	Descrição
contactId	uuid	ID do contato externo.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome da tag a aplicar (criada se não existir).

curl -X POST "https://api.squados.io/v1/contacts/CONTACT_ID/tags" \
  -H "Authorization: Bearer pk_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{"name": "lead quente"}'

Resposta — 200 OK

{
  "tag": { "id": "8a1b2c3d-4e5f-6789-abcd-ef0123456789", "name": "lead quente", "color": "orange" }
}

Erros relevantes: 400 invalid_request para JSON malformado, name ausente/não textual/vazio ou contactId inválido; 404 not_found se o contato não existir ou não pertencer à sua organização; 500 internal_error se a aplicação falhar.

---

DELETE /contacts/{contactId}/tags/{tagId}

Remove a tag do contato. A tag permanece no catálogo da organização e em outros contatos. A operação é idempotente: IDs válidos recebem 200 mesmo quando a associação já não existe ou o tagId não pertence a uma tag aplicada ao contato.

Parâmetros de caminho

Nome	Tipo	Descrição
contactId	uuid	ID do contato externo.
tagId	uuid	ID da tag a remover.

curl -X DELETE "https://api.squados.io/v1/contacts/CONTACT_ID/tags/TAG_ID" \
  -H "Authorization: Bearer pk_sua_chave_aqui"

Resposta — 200 OK

{ "success": true }

Erros relevantes: 400 invalid_request se algum ID for inválido; 404 not_found se o contato não existir ou não pertencer à sua organização; 500 internal_error se a remoção falhar.

Cuidado

As verificações de existência de contato e tag ignoram erros de consulta no runtime atual. Por isso, um 404 pode representar uma falha transitória de lookup. Confirme o recurso com uma nova leitura antes de descartá-lo do estado local.

Dica

Prefere testar no navegador? Os mesmos endpoints estão no Swagger interativo, na seção Tags — cole seu token e dispare as chamadas direto de lá.

O Swagger atual não enumera os 500 implementados por cinco destas operações. Trate 5xx como transitório, aplique backoff com jitter e reconcilie o resultado por GET /tags ou GET /contacts/{contactId}/tags antes de repetir uma mutação.