---
title: "Comandos contact.*"
slug: "comandos-contact"
updated: 2026-09-10T18:50:01Z
published: 2026-09-10T18:50:01Z
canonical: "docs.omnisiga.ai/comandos-contact"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omnisiga.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Comandos contact.*

## Comandos `contact.*`

| Família | Finalidade |
| --- | --- |
| `contact.*` | Consulta, criação, atualização de contatos, atributos, campos customizados e tags. |

## Como usar

- `contact.*` opera no contexto da organização e da sessão atual.
- Use `contact.get()` quando o contato já tiver sido associado automaticamente à sessão.
- Prefira `upsert(...)` ou `upsertBy(...)` quando o fluxo precisa criar o contato caso ele ainda não exista.
- Use o identificador correto para a busca. Um telefone formatado para exibição pode não ser igual ao telefone canônico armazenado.
- `customId` não deve ser tratado como telefone normalizado. Usar valores inconsistentes pode gerar contatos duplicados.
- O catálogo documenta `customId`, `email`, `phone`, `whatsapp`, `instagram`, `facebook` e `telegram` como tipos de `findBy(...)`.
- Implementações mais recentes também registram `bsuid` em `findBy(...)` e `upsertBy(...)`; confirme a versão do serviço antes de utilizá-lo.
- A criação ou alteração de atributos, campos customizados e tags pode afetar outros fluxos que usam o mesmo contato.

---

## Busca

#### `contact.get()`

Retorna o contato vinculado à sessão atual (via `session.contactId`). Retorna `null` se não houver contato vinculado.

```
var contato = contact.get();
if (contato != null) { dialog.say('Olá, ' + contato.name); }
```

#### `contact.findById(id)`

Busca um contato pelo ID interno da plataforma.

```
var contato = contact.findById('abc-123');
```

#### `contact.findByCustomId(customId)`

Busca um contato pelo `customId` (ex: CPF, matrícula).

```
var contato = contact.findByCustomId(variables.get('cpf'));
```

#### `contact.find(customId)`

Alias de `findByCustomId()`. Prefira `findByCustomId()` em novos scripts.

```
var contato = contact.find(variables.get('cpf'));
```

#### `contact.findBy(type, value)`

Busca um contato por tipo de campo e valor. Tipos suportados: `'customId'`, `'email'`, `'phone'`, `'whatsapp'`, `'instagram'`, `'facebook'`, `'telegram'`.

```
var contato = contact.findBy('email', variables.get('emailDigitado'));
var contato = contact.findBy('whatsapp', variables.get('telefone'));
```

---

## Criação e upsert

#### `contact.createContact(name, customId, attributes)`

Cria um novo contato com nome, customId e atributos.

```
var contato = contact.createContact('João Silva', variables.get('cpf'), {'email': variables.get('email')});
```

#### `contact.createContact(customId, attributes)`

Cria um novo contato sem nome explícito (nome gravado como `'notset'`).

```
var contato = contact.createContact(variables.get('cpf'), {email: variables.get('email')});
```

#### `contact.upsert(customId, name, attributes)`

Cria ou atualiza um contato identificado pelo customId. Use quando não se sabe se o contato já está cadastrado.

```
var contato = contact.upsert(variables.get('cpf'), variables.get('nome'), {'email': variables.get('email')});
```

#### `contact.upsertBy(field, value, name, attributes)`

Cria ou atualiza um contato identificado por campo e valor arbitrários (ex: `'email'`, `'phone'`).

```
var contato = contact.upsertBy('email', variables.get('email'), variables.get('nome'), {});
```

---

## Atributos

#### `contact.addAttribute(contactId, key, value)`

Adiciona ou atualiza um atributo em um contato. Retorna o contato atualizado. Se o valor for um objeto JS ou Contact, é serializado para JSON.

```
contact.addAttribute(contato.id, 'plano', 'premium');
```

#### `contact.addAttributeToContact(contactId, key, value)`

Equivalente a `addAttribute`, mas sem retornar o contato atualizado.

```
contact.addAttributeToContact(contato.id, 'status', 'ativo');
```

#### `contact.removeAttributeFromContact(contactId, key)`

Remove um atributo de um contato.

```
contact.removeAttributeFromContact(contato.id, 'tokenTemporario');
```

#### `contact.getAttributeFromContact(contactId, key)`

Retorna o valor de um atributo de um contato. Lança `IllegalArgumentException` se o contato não for encontrado.

```
var plano = contact.getAttributeFromContact(contato.id, 'plano');
```

#### `contact.getContactAttributes(contactId)`

Retorna todos os atributos de um contato como string JSON.

```
var attrs = JSON.parse(contact.getContactAttributes(contato.id));
```

---

## Campos customizados

#### `contact.setCustomFieldOfContact(contactId, fieldName, value)`

Define o valor de um campo customizado em um contato (valor convertido para string).

```
contact.setCustomFieldOfContact(contato.id, 'numeroContrato', variables.get('contrato'));
```

#### `contact.getCustomFieldFromContact(contactId, fieldName)`

Retorna o valor de um campo customizado como string, ou `null` se não definido.

```
var contrato = contact.getCustomFieldFromContact(contato.id, 'numeroContrato');
```

#### `contact.removeCustomFieldFromContact(contactId, fieldName)`

Remove um campo customizado de um contato.

```
contact.removeCustomFieldFromContact(contato.id, 'tokenProvisorio');
```

---

## Tags de contato

#### `contact.addTagsToContact(contactId, tags)`

Adiciona tags a um contato (separadas por vírgula). Retorna o contato atualizado.

```
contact.addTagsToContact(contato.id, 'cliente-vip,renovacao-2024');
```

#### `contact.removeTagsToContact(contactId, tags)`

Remove tags de um contato. Retorna o contato atualizado.

```
contact.removeTagsToContact(contato.id, 'em-analise');
```

#### `contact.getTagsFromContact(contactId)`

Retorna as tags de um contato como string. Lança `IllegalArgumentException` se não encontrado.

```
var tags = contact.getTagsFromContact(contato.id);
```

---

---