API — Labels

Labels (etiquetas) são marcadores classificatórios aplicáveis a conversas, contatos e negócios. Esta página cobre os endpoints para gerenciar as definições de etiqueta (criar/excluir) e aplicar em recursos.

Endpoints

Gerenciar definições

Método	Endpoint	Ação
GET	/api/v1/accounts/{id}/labels	Lista etiquetas
POST	/api/v1/accounts/{id}/labels	Cria etiqueta
GET	/api/v1/accounts/{id}/labels/{label_id}	Detalhes
PATCH	/api/v1/accounts/{id}/labels/{label_id}	Atualizar
DELETE	/api/v1/accounts/{id}/labels/{label_id}	Remover

Aplicar em recursos

Método	Endpoint	Ação
POST	/api/v1/accounts/{id}/conversations/{conv_id}/labels	Aplicar em conversa
POST	/api/v1/accounts/{id}/contacts/{contact_id}/labels	Aplicar em contato
PATCH	/api/v1/accounts/{id}/deals/{deal_id}	Etiquetar negócio — as etiquetas vão no campo labels do próprio negócio

Campos do recurso

{
  "id": 25,
  "title": "vip",
  "description": "Cliente Premium ou alto LTV",
  "color": "#8B5CF6",
  "show_on_sidebar": true,
  "conversations_count": 145,
  "contacts_count": 89,
  "created_at": "2024-01-15T10:00:00Z"
}

POST /labels

curl -X POST "https://app.smart2.com.br/api/v1/accounts/1/labels" \
  -H "api_access_token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "vip",
    "description": "Cliente VIP — prioridade máxima",
    "color": "#8B5CF6",
    "show_on_sidebar": true
  }'

Convenção de nomenclatura

Use lowercase com hífen:

• ✅ lead-novo, vip, motivo-cancelamento
• ❌ Lead Novo, VIP_Tag, motivo cancelamento

Aplicar etiquetas em conversa

curl -X POST "https://app.smart2.com.br/api/v1/accounts/1/conversations/8821/labels" \
  -H "api_access_token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "labels": ["vip", "urgente"]
  }'

Nota

Esse endpoint substitui todas as etiquetas atuais. Para adicionar mantendo as existentes, faça GET → merge → POST.

Adicionar mantendo existentes (pattern)

# Pega etiquetas atuais
conv = requests.get(f"{BASE_URL}/conversations/8821", headers=HEADERS).json()
current_labels = conv.get('labels', [])

# Adiciona nova
new_labels = list(set(current_labels + ['vip']))

# Substitui
requests.post(
    f"{BASE_URL}/conversations/8821/labels",
    headers=HEADERS,
    json={"labels": new_labels}
)

Remover etiqueta específica

new_labels = [l for l in current_labels if l != 'vip']
requests.post(
    f"{BASE_URL}/conversations/8821/labels",
    headers=HEADERS,
    json={"labels": new_labels}
)

Aplicar etiquetas em contato

curl -X POST "https://app.smart2.com.br/api/v1/accounts/1/contacts/4521/labels" \
  -d '{
    "labels": ["vip", "indicacao", "region-sp"]
  }'

Mesma lógica de substituição. Etiqueta no contato vale para a pessoa em todas as conversas; etiqueta na conversa vale apenas para aquele atendimento.

PATCH /labels/{label_id}

Renomear ou alterar cor.

curl -X PATCH "https://app.smart2.com.br/api/v1/accounts/1/labels/25" \
  -d '{
    "title": "cliente-vip",
    "color": "#A855F7"
  }'

Nota

Renomear atualiza retroativamente — todas as conversas que tinham a etiqueta antiga passam a mostrar o novo nome.

DELETE /labels/{label_id}

Cuidado

Remove a etiqueta de todos os lugares onde estava aplicada (conversas, contatos, deals). Irreversível.

curl -X DELETE "https://app.smart2.com.br/api/v1/accounts/1/labels/25"

Casos de uso

Setup inicial de labels padrão

labels = [
    {"title": "vip", "color": "#8B5CF6"},
    {"title": "lead-novo", "color": "#3B82F6"},
    {"title": "lead-frio", "color": "#94A3B8"},
    {"title": "lead-quente", "color": "#EF4444"},
    {"title": "cliente-ativo", "color": "#10B981"},
    {"title": "cliente-inativo", "color": "#6B7280"},
    {"title": "motivo-cancelamento", "color": "#F59E0B"},
    {"title": "motivo-troca", "color": "#06B6D4"}
]

for l in labels:
    requests.post(f"{BASE_URL}/labels", headers=HEADERS, json={
        **l,
        "show_on_sidebar": False
    })

Aplicar etiqueta com base em comportamento

# Marcar como "lead-quente" se contato enviou >5 mensagens em 24h
recent_messages = count_recent_messages(contact_id, hours=24)
if recent_messages > 5:
    contact = requests.get(f"{BASE_URL}/contacts/{contact_id}", headers=HEADERS).json()
    labels = list(set(contact['labels'] + ['lead-quente']))
    requests.post(
        f"{BASE_URL}/contacts/{contact_id}/labels",
        headers=HEADERS,
        json={"labels": labels}
    )

Limpar etiquetas obsoletas em massa

# Identifica labels sem uso há 90 dias
all_labels = requests.get(f"{BASE_URL}/labels", headers=HEADERS).json()['payload']

obsolete = [l for l in all_labels if l['conversations_count'] == 0 and l['contacts_count'] == 0]

for l in obsolete:
    print(f"Removendo etiqueta sem uso: {l['title']}")
    requests.delete(f"{BASE_URL}/labels/{l['id']}", headers=HEADERS)

Sincronizar etiquetas com sistema de tags externo

external_tags = fetch_tags_from_external_system(contact_id)

# Mapeia tag externa pra label app.smart
label_mapping = {
    "VIP_Customer": "vip",
    "Active_Subscription": "cliente-ativo",
    "Cancellation_Risk": "risco-cancelamento"
}

mapped_labels = [label_mapping[t] for t in external_tags if t in label_mapping]

requests.post(
    f"{BASE_URL}/contacts/{contact_id}/labels",
    headers=HEADERS,
    json={"labels": mapped_labels}
)

Próximos passos

• Conversations — aplicar labels em conversas
• Contacts — aplicar labels em contatos
• Manual — Etiquetas