Criar ou atualizar um contato

Procure o contato pelo telefone, crie se não existir (com etiqueta, campo e fluxo) e, se existir, atualize as etiquetas e os campos. Sem criar duplicados.

Guia10 min

Atualizado em 26/10/2026

Quando o seu sistema recebe um cadastro, uma venda ou um formulário, ele precisa deixar o contato pronto na NexTags. O caminho seguro tem três partes: procurar o contato pelo telefone, criar só se ele não existir e, se existir, atualizar as etiquetas e os campos. Procurar antes evita contatos repetidos, porque o contrato da API não diz o que acontece quando você cria um telefone que já existe.

Antes de começar

A chave de API na variável de ambiente NEXTAGS_API_KEY. Veja Autenticação com a chave de API.
O telefone completo, só com números: código do país, DDD e número, como 5511988776655. Veja O formato certo do telefone.
A etiqueta e o campo que você vai usar, já criados na conta, com os IDs anotados (neste guia, a etiqueta cliente-vip, ID 2001, e o campo cidade, ID 3001). Veja Contatos, fluxos e outros identificadores.
Se for enviar um fluxo ao contato novo: o ID do fluxo. No WhatsApp, o fluxo precisa começar com um Modelo de Mensagem aprovado, porque o contato novo ainda não falou com você. Veja Modelo de mensagem do WhatsApp no fluxo.

Passo a passo

Passo 1: Procure o contato pelo telefone

Use Buscar contato por campo personalizado com field_id=phone e o telefone em value. Para procurar pelo e-mail, use field_id=email.

Procurar pelo telefone

curl "https://app.nextagsai.com.br/api/contacts/find_by_custom_field?field_id=phone&value=5511988776655" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"

const resposta = await fetch(`https://app.nextagsai.com.br/api/contacts/find_by_custom_field?${new URLSearchParams({
  field_id: 'phone',
  value: '5511988776655',
})}`, {
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
});
const dados = await resposta.json();
console.log(resposta.status, dados);

import os

import requests

resposta = requests.get(
    "https://app.nextagsai.com.br/api/contacts/find_by_custom_field",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    params={
        "field_id": "phone",
        "value": "5511988776655",
    },
    timeout=30,
)
print(resposta.status_code, resposta.json())

<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/find_by_custom_field?' . http_build_query([
    'field_id' => 'phone',
    'value' => '5511988776655',
]));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);

Se o contato existe, ele vem na lista data (aqui, resumido; os campos estão em Consultar contato):

{
  "data": [
    {
      "id": 123456789,
      "first_name": "Ana",
      "last_name": "Souza",
      "channel": 5,
      "tags": [{"id": 2001, "name": "cliente-vip"}],
      "custom_fields": [
        {"id": 3001, "name": "cidade", "type": 0, "value": "São Paulo"}
      ]
    }
  ]
}

Se data vier vazia ou não vier, o contato não existe: siga para o passo 2. Se vier, guarde o id e pule para o passo 3. Com mais de um resultado, veja Encontrar um contato pelo e-mail ou telefone.

Passo 2: Se não achou, crie o contato

Use Criar contato. O phone é obrigatório; email, first_name, last_name e gender (male, female ou unknown) são opcionais. Em actions, a mesma chamada já põe a etiqueta, preenche o campo e envia um fluxo, pelo nome da etiqueta e do campo.

Criar contato

curl -X POST "https://app.nextagsai.com.br/api/contacts" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511988776655",
    "email": "ana@exemplo.com.br",
    "first_name": "Ana",
    "last_name": "Souza",
    "gender": "female",
    "actions": [
      {
        "action": "add_tag",
        "tag_name": "cliente-vip"
      },
      {
        "action": "set_field_value",
        "field_name": "cidade",
        "value": "São Paulo"
      },
      {
        "action": "send_flow",
        "flow_id": 1000001
      }
    ]
  }'

const resposta = await fetch('https://app.nextagsai.com.br/api/contacts', {
  method: 'POST',
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    phone: '5511988776655',
    email: 'ana@exemplo.com.br',
    first_name: 'Ana',
    last_name: 'Souza',
    gender: 'female',
    actions: [
      {
        action: 'add_tag',
        tag_name: 'cliente-vip',
      },
      {
        action: 'set_field_value',
        field_name: 'cidade',
        value: 'São Paulo',
      },
      {
        action: 'send_flow',
        flow_id: 1000001,
      },
    ],
  }),
});
const dados = await resposta.json();
console.log(resposta.status, dados);

import os

import requests

resposta = requests.post(
    "https://app.nextagsai.com.br/api/contacts",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    json={
        "phone": "5511988776655",
        "email": "ana@exemplo.com.br",
        "first_name": "Ana",
        "last_name": "Souza",
        "gender": "female",
        "actions": [
            {
                "action": "add_tag",
                "tag_name": "cliente-vip",
            },
            {
                "action": "set_field_value",
                "field_name": "cidade",
                "value": "São Paulo",
            },
            {
                "action": "send_flow",
                "flow_id": 1000001,
            },
        ],
    },
    timeout=30,
)
print(resposta.status_code, resposta.json())

<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'phone' => '5511988776655',
        'email' => 'ana@exemplo.com.br',
        'first_name' => 'Ana',
        'last_name' => 'Souza',
        'gender' => 'female',
        'actions' => [
            [
                'action' => 'add_tag',
                'tag_name' => 'cliente-vip',
            ],
            [
                'action' => 'set_field_value',
                'field_name' => 'cidade',
                'value' => 'São Paulo',
            ],
            [
                'action' => 'send_flow',
                'flow_id' => 1000001,
            ],
        ],
    ]),
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);

O contrato não descreve o que a criação responde. Para ter o ID do contato novo, procure de novo pelo telefone, como no passo 1. As ações e o formato de cada uma estão em Mensagens e ações em JSON.

Passo 3: Se achou, ponha a etiqueta

Use Adicionar etiqueta ao contato, com o ID do contato e o da etiqueta no caminho. Não tem corpo.

Adicionar etiqueta ao contato

curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/tags/2001" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"

const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/tags/2001', {
  method: 'POST',
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
});
const dados = await resposta.json();
console.log(resposta.status, dados);

import os

import requests

resposta = requests.post(
    "https://app.nextagsai.com.br/api/contacts/123456789/tags/2001",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    timeout=30,
)
print(resposta.status_code, resposta.json())

<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/123456789/tags/2001');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);

A resposta é {"success": true}. Para tirar uma etiqueta, use DELETE no mesmo endereço (Remover etiqueta do contato).

Passo 4: Preencha os campos

Use Preencher campo do contato. Esta chamada recebe formulário, não JSON: o valor vai no campo value.

Preencher campo do contato

curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \
  --data-urlencode 'value=São Paulo'

const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001', {
  method: 'POST',
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
  },
  body: new URLSearchParams({
    value: 'São Paulo',
  }),
});
const dados = await resposta.json();
console.log(resposta.status, dados);

import os

import requests

resposta = requests.post(
    "https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    data={
        "value": "São Paulo",
    },
    timeout=30,
)
print(resposta.status_code, resposta.json())

<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
    ],
    CURLOPT_POSTFIELDS => http_build_query([
        'value' => 'São Paulo',
    ]),
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);

A resposta é {"success": true}. Data vai em Unix timestamp em segundos e sim/não em 1 ou 0. Veja Campos personalizados, campos do bot e variáveis.

Passo 5: Atualize o nome ou o e-mail, se mudaram

A API não tem uma chamada de atualizar contato. Para trocar o nome, o e-mail ou o telefone de quem já existe, mande só ações em Enviar conteúdo, com set_field_value e os campos do sistema first_name, last_name, full_name, email ou phone.

Atualizar o e-mail e o sobrenome

curl -X POST "https://app.nextagsai.com.br/api/contacts/123456789/send_content" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "actions": [
      {
        "action": "set_field_value",
        "field_name": "email",
        "value": "ana.souza@exemplo.com.br"
      },
      {
        "action": "set_field_value",
        "field_name": "last_name",
        "value": "Souza Lima"
      }
    ]
  }'

const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/send_content', {
  method: 'POST',
  headers: {
    'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    actions: [
      {
        action: 'set_field_value',
        field_name: 'email',
        value: 'ana.souza@exemplo.com.br',
      },
      {
        action: 'set_field_value',
        field_name: 'last_name',
        value: 'Souza Lima',
      },
    ],
  }),
});
const dados = await resposta.json();
console.log(resposta.status, dados);

import os

import requests

resposta = requests.post(
    "https://app.nextagsai.com.br/api/contacts/123456789/send_content",
    headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
    json={
        "actions": [
            {
                "action": "set_field_value",
                "field_name": "email",
                "value": "ana.souza@exemplo.com.br",
            },
            {
                "action": "set_field_value",
                "field_name": "last_name",
                "value": "Souza Lima",
            },
        ],
    },
    timeout=30,
)
print(resposta.status_code, resposta.json())

<?php
$ch = curl_init('https://app.nextagsai.com.br/api/contacts/123456789/send_content');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'actions' => [
            [
                'action' => 'set_field_value',
                'field_name' => 'email',
                'value' => 'ana.souza@exemplo.com.br',
            ],
            [
                'action' => 'set_field_value',
                'field_name' => 'last_name',
                'value' => 'Souza Lima',
            ],
        ],
    ]),
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);

Sem messages, nada é enviado ao contato. Confira o resultado no painel do contato depois do primeiro teste.

Passo 6: Junte tudo numa função

A função procura pelo telefone, cria se não achar e, se achar, põe a etiqueta e preenche o campo. Rode com a chave em NEXTAGS_API_KEY.

Criar ou atualizar

const BASE = 'https://app.nextagsai.com.br/api';

async function api(metodo, caminho, { json, form } = {}) {
  const headers = { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY };
  let body;
  if (json) {
    headers['Content-Type'] = 'application/json';
    body = JSON.stringify(json);
  }
  if (form) body = new URLSearchParams(form);
  const resposta = await fetch(BASE + caminho, { method: metodo, headers, body });
  const texto = await resposta.text();
  if (!resposta.ok) throw new Error(`${metodo} ${caminho}: ${resposta.status} ${texto}`);
  try { return JSON.parse(texto); } catch { return texto; }
}

async function acharPeloTelefone(telefone) {
  const consulta = new URLSearchParams({ field_id: 'phone', value: telefone });
  const resposta = await api('GET', `/contacts/find_by_custom_field?${consulta}`);
  const lista = (resposta && resposta.data) || [];
  return lista[0] || null; // o de mudança mais recente vem primeiro
}

async function criarOuAtualizar({ telefone, email, nome, sobrenome, cidade }) {
  const contato = await acharPeloTelefone(telefone);
  if (!contato) {
    await api('POST', '/contacts', {
      json: {
        phone: telefone,
        email,
        first_name: nome,
        last_name: sobrenome,
        actions: [
          { action: 'add_tag', tag_name: 'cliente-vip' },
          { action: 'set_field_value', field_name: 'cidade', value: cidade },
        ],
      },
    });
    return acharPeloTelefone(telefone); // para ter o ID do contato novo
  }
  await api('POST', `/contacts/${contato.id}/tags/2001`);
  await api('POST', `/contacts/${contato.id}/custom_fields/3001`, { form: { value: cidade } });
  return contato;
}

const contato = await criarOuAtualizar({
  telefone: '5511988776655',
  email: 'ana@exemplo.com.br',
  nome: 'Ana',
  sobrenome: 'Souza',
  cidade: 'São Paulo',
});
console.log(contato && contato.id);

import json
import os

import requests

BASE = "https://app.nextagsai.com.br/api"


def api(metodo, caminho, json_corpo=None, form=None, params=None):
    resposta = requests.request(
        metodo,
        BASE + caminho,
        headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
        json=json_corpo,
        data=form,
        params=params,
        timeout=30,
    )
    if not resposta.ok:
        raise RuntimeError(f"{metodo} {caminho}: {resposta.status_code} {resposta.text}")
    try:
        return resposta.json()
    except json.JSONDecodeError:
        return resposta.text


def achar_pelo_telefone(telefone):
    resposta = api("GET", "/contacts/find_by_custom_field", params={"field_id": "phone", "value": telefone})
    lista = resposta.get("data") if isinstance(resposta, dict) else None
    return lista[0] if lista else None  # o de mudança mais recente vem primeiro


def criar_ou_atualizar(telefone, email, nome, sobrenome, cidade):
    contato = achar_pelo_telefone(telefone)
    if contato is None:
        api("POST", "/contacts", json_corpo={
            "phone": telefone,
            "email": email,
            "first_name": nome,
            "last_name": sobrenome,
            "actions": [
                {"action": "add_tag", "tag_name": "cliente-vip"},
                {"action": "set_field_value", "field_name": "cidade", "value": cidade},
            ],
        })
        return achar_pelo_telefone(telefone)  # para ter o ID do contato novo
    api("POST", f"/contacts/{contato['id']}/tags/2001")
    api("POST", f"/contacts/{contato['id']}/custom_fields/3001", form={"value": cidade})
    return contato


contato = criar_ou_atualizar("5511988776655", "ana@exemplo.com.br", "Ana", "Souza", "São Paulo")
print(contato and contato["id"])

<?php
const BASE = 'https://app.nextagsai.com.br/api';

function api(string $metodo, string $caminho, ?array $json = null, ?array $form = null)
{
    $cabecalhos = ['X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY')];
    $opcoes = [CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => $metodo, CURLOPT_TIMEOUT => 30];
    if ($json !== null) {
        $cabecalhos[] = 'Content-Type: application/json';
        $opcoes[CURLOPT_POSTFIELDS] = json_encode($json);
    }
    if ($form !== null) {
        $opcoes[CURLOPT_POSTFIELDS] = http_build_query($form);
    }
    $opcoes[CURLOPT_HTTPHEADER] = $cabecalhos;
    $ch = curl_init(BASE . $caminho);
    curl_setopt_array($ch, $opcoes);
    $texto = curl_exec($ch);
    $codigo = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    if ($codigo < 200 || $codigo >= 300) {
        throw new RuntimeException("$metodo $caminho: $codigo $texto");
    }
    $dados = json_decode($texto, true);
    return $dados ?? $texto;
}

function acharPeloTelefone(string $telefone): ?array
{
    $resposta = api('GET', '/contacts/find_by_custom_field?' . http_build_query(['field_id' => 'phone', 'value' => $telefone]));
    $lista = is_array($resposta) ? ($resposta['data'] ?? []) : [];
    return $lista[0] ?? null; // o de mudança mais recente vem primeiro
}

function criarOuAtualizar(string $telefone, string $email, string $nome, string $sobrenome, string $cidade): ?array
{
    $contato = acharPeloTelefone($telefone);
    if ($contato === null) {
        api('POST', '/contacts', [
            'phone' => $telefone,
            'email' => $email,
            'first_name' => $nome,
            'last_name' => $sobrenome,
            'actions' => [
                ['action' => 'add_tag', 'tag_name' => 'cliente-vip'],
                ['action' => 'set_field_value', 'field_name' => 'cidade', 'value' => $cidade],
            ],
        ]);
        return acharPeloTelefone($telefone); // para ter o ID do contato novo
    }
    api('POST', "/contacts/{$contato['id']}/tags/2001");
    api('POST', "/contacts/{$contato['id']}/custom_fields/3001", null, ['value' => $cidade]);
    return $contato;
}

$contato = criarOuAtualizar('5511988776655', 'ana@exemplo.com.br', 'Ana', 'Souza', 'São Paulo');
echo $contato['id'] ?? 'não encontrado', PHP_EOL;

Repetir a função com os mesmos dados não cria outro contato: na segunda vez, a busca acha o primeiro.

Pronto: como conferir

Procure de novo pelo telefone: o contato vem com a etiqueta em tags e o valor em custom_fields.
Na NexTags, abra o contato na Caixa de Entrada: o painel mostra a etiqueta e o campo. Veja O painel Mais informações.
Para conferir só as etiquetas ou só os campos, use Listar etiquetas do contato e Listar campos do contato.

Se não funcionou

401 com "No valid API key provided."

A chave não chegou ou não vale. Veja Autenticação com a chave de API.

A busca não acha um contato que existe

O telefone pode estar salvo noutro formato (sem o 55, com + ou sem o 9), e não foi conferido se a busca acha esses casos. Procure também pelo e-mail e padronize os telefones do seu sistema no formato completo, só com números.

O mesmo contato apareceu duas vezes

A criação rodou sem a busca antes, ou a busca usou um formato de telefone diferente do salvo. Procure sempre antes de criar, com o mesmo formato de telefone. Para limpar os repetidos, use a tela: veja Ações em massa.

O contato novo não recebeu o fluxo

No WhatsApp, o contato novo está fora da janela de 24 horas: o fluxo precisa começar com um Modelo de Mensagem aprovado. Confira também se o fluxo está publicado. Veja A janela de 24 horas e Enviar um fluxo para um contato.

A etiqueta ou o campo não foram preenchidos na criação

As ações acham a etiqueta e o campo pelo nome exato, com maiúsculas, acentos e espaços. Confira o nome em Fluxos › Etiquetas e Campo Personalizados, ou use os passos 3 e 4, que usam o ID.

400 ou 404 ao pôr a etiqueta ou preencher o campo

O ID do contato, da etiqueta ou do campo está errado ou é de outra conta. Confira os IDs em Contatos, fluxos e outros identificadores.

Faça com a IA

Copie o pedido e cole no ChatGPT ou no Claude.

Leia https://docs.nextags.com.br/guias/criar-ou-atualizar-contato.md e https://docs.nextags.com.br/comecar/mensagens-e-acoes.md.

Escreva, em [linguagem], uma função que recebe um cadastro do [seu sistema, por exemplo: checkout da loja] com nome, e-mail, telefone e [outros dados] e cria ou atualiza o contato na NexTags: procura pelo telefone, cria se não existir (com a etiqueta [nome] e o campo [nome]) e, se existir, atualiza a etiqueta e o campo pelos IDs [IDs]. A chave vem da variável de ambiente NEXTAGS_API_KEY. Trate o erro 401 e não crie contato sem procurar antes.

Obrigado! Sua resposta ajuda a melhorar a central.