Skip to main content

​
Contatos

API dedicada para gerenciar contatos da sua instância. Todos os endpoints criam o contato automaticamente se o telefone informado ainda não existir na base.
Todos os endpoints requerem o header X-Client-Token. Veja Autenticação.

​
Base URL

https://wapi.stegia.com.br/functions/v1/contacts-api

​
Criar Contato

POST /contacts-api/create
Cria um novo contato com dados completos. Se já existir (por phone + instanceId), os campos enviados são atualizados (idempotente).

​
Parâmetros

CampoTipoObrigatórioDescrição
instanceIdstring✅ID da instância
phonestring✅Número (formato: 5511999999999)
namestring❌Nome do contato
emailstring❌E-mail
companystring❌Empresa
jobTitlestring❌Cargo
notesstring❌Anotações livres
tagsarray<string>❌Nomes de etiquetas (cria automaticamente se não existir)
utmSourcestring❌Origem UTM
utmMediumstring❌Meio UTM
utmCampaignstring❌Campanha UTM
customLabelsobject❌Campos customizados (chave/valor)

​
Exemplo

curl -X POST "https://wapi.stegia.com.br/functions/v1/contacts-api/create" \
  -H "Content-Type: application/json" \
  -H "X-Client-Token: SEU_TOKEN" \
  -d '{
    "instanceId": "SUA_INSTANCIA",
    "phone": "5511999999999",
    "name": "João Silva",
    "email": "joao@email.com",
    "company": "ACME Corp",
    "jobTitle": "Diretor",
    "notes": "Lead vindo do evento X",
    "tags": ["vip", "lead-quente"],
    "utmSource": "google",
    "customLabels": { "segmento": "premium", "tier": "ouro" }
  }'

​
Resposta

{
  "success": true,
  "action": "created",
  "contactId": "uuid-do-contato",
  "tagsApplied": ["vip", "lead-quente"]
}

​
Atualizar Contato

POST /contacts-api/update
Atualiza campos de um contato existente. Se não existir, é criado. Tags são adicionadas, não substituem as existentes.

​
Parâmetros

Mesmos campos do /create, mais:
CampoTipoObrigatórioDescrição
isFavoriteboolean❌Marcar como favorito
isArchivedboolean❌Arquivar
isBlockedboolean❌Bloquear

​
Exemplo

curl -X POST "https://wapi.stegia.com.br/functions/v1/contacts-api/update" \
  -H "Content-Type: application/json" \
  -H "X-Client-Token: SEU_TOKEN" \
  -d '{
    "instanceId": "SUA_INSTANCIA",
    "phone": "5511999999999",
    "company": "Nova Empresa LTDA",
    "notes": "Atualizado via integração CRM",
    "tags": ["cliente-ativo"]
  }'

​
Resposta

{
  "success": true,
  "action": "updated",
  "contactId": "uuid-do-contato",
  "fieldsUpdated": ["company", "notes"],
  "tagsApplied": ["cliente-ativo"]
}

​
Gerenciar Etiquetas

POST /contacts-api/tags
Adiciona e/ou remove etiquetas de um contato em uma única chamada.

​
Parâmetros

CampoTipoObrigatórioDescrição
instanceIdstring✅ID da instância
phonestring✅Número do contato
addTagsarray<string>❌Etiquetas para adicionar (cria se não existir)
removeTagsarray<string>❌Etiquetas para remover

​
Exemplo

curl -X POST "https://wapi.stegia.com.br/functions/v1/contacts-api/tags" \
  -H "Content-Type: application/json" \
  -H "X-Client-Token: SEU_TOKEN" \
  -d '{
    "instanceId": "SUA_INSTANCIA",
    "phone": "5511999999999",
    "addTags": ["vip", "convertido"],
    "removeTags": ["lead-frio"]
  }'

​
Resposta

{
  "success": true,
  "contactId": "uuid-do-contato",
  "tagsApplied": ["vip", "convertido"],
  "tagsRemoved": ["lead-frio"]
}

​
Comportamentos Automáticos

Se o phone informado não existir na sua instância, o sistema cria automaticamente um novo contato com origin: "api" antes de aplicar quaisquer outras operações (atualização, tags, etc).
O parâmetro tags aceita nomes (strings), não UUIDs. Se a etiqueta não existir na instância, ela é criada automaticamente com uma cor aleatória e fica disponível para uso futuro no painel.
O endpoint /create é seguro para chamar múltiplas vezes — se o contato já existir, ele apenas atualiza os campos enviados sem duplicar registros.
O sistema reconhece automaticamente variações do número brasileiro (com/sem nono dígito), garantindo que 5511999999999 e 551199999999 sejam tratados como o mesmo contato.