Comandos contact.*

Comandos contact.*

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);