Pular para o conteúdo principal

Contatos

Os campos de contato são uma parte central de como a Turn.io armazena dados relacionados a um determinado contato.
Oferecemos alguns campos padrão para todos os contatos, bem como a capacidade de criar seus próprios campos personalizados.
Você pode gerenciar os campos de contato na interface do usuário em Configurações > Pessoas e importar e segmentar seus usuários na aba Pessoas.

Como alternativa, documentamos abaixo como você pode realizar as seguintes ações programaticamente com nossa API REST:

  1. Gerenciar seu esquema de contato
  2. Gerenciar dados de contatos individuais
  3. Importar contatos em massa

API de Perfil de Contatos da Turn.io​

Por padrão, os seguintes campos são reservados e imediatamente disponíveis para todos os contatos na Turn.io:

  • name: STRING, pode ser null
  • surname: STRING, pode ser null
  • location: LOCATION, pode ser null
  • language: ENUM, limitado a códigos de país ISO-639-3, pode ser null
  • opted_in: BOOLEAN, padrão é false
  • opted_in_at: DATETIME, pode ser null
  • birthday: DATETIME, pode ser null
  • whatsapp_profile_name: STRING, pode ser null
  • whatsapp_id: STRING, pode ser null

Qualquer campo criado usando o endpoint /v1/contacts/schema será adicionado a esses campos.

Obtendo o Esquema do Perfil de Contato​

Para obter o esquema atual para um determinado número, você pode fazer o seguinte:

curl https://whatsapp.turn.io/v1/contacts/schemas \
    -H 'Authorization: Bearer token' \
    -H 'Content-Type: application/json'

> {
  "fields": [
    {
      "custom": false,
      "default": null,
      "display": "Nome do Perfil do WhatsApp",
      "is_private": true,
      "name": "whatsapp_profile_name",
      "null": true,
      "type": "STRING"
    },
    {
      "custom": false,
      "default": null,
      "display": "Última Visualização",
      "is_private": false,
      "name": "last_seen_at",
      "null": true,
      "type": "DATETIME"
    },
    {
      "custom": false,
      "default": null,
      "display": "Nome",
      "is_private": true,
      "name": "name",
      "null": true,
      "type": "STRING"
    },
    {
      "custom": false,
      "default": null,
      "display": "Sobrenome",
      "is_private": true,
      "name": "surname",
      "null": true,
      "type": "STRING"
    },
    {
      "custom": false,
      "default": null,
      "display": "Localização",
      "is_private": true,
      "name": "location",
      "null": true,
      "type": "LOCATION"
    },
    {
      "custom": false,
      "default": false,
      "display": "Optou por Participar",
      "is_private": false,
      "name": "opted_in",
      "null": false,
      "type": "BOOLEAN"
    },
    {
      "custom": false,
      "default": null,
      "display": "Idioma",
      "enum": [],
      "is_private": true,
      "name": "language",
      "null": true,
      "type": "ENUM"
    },
    {
      "custom": false,
      "default": null,
      "display": "Aniversário",
      "is_private": true,
      "name": "birthday",
      "null": true,
      "type": "DATETIME"
    },
    {
      "custom": false,
      "default": null,
      "display": "Primeira Mensagem Recebida Em",
      "is_private": false,
      "name": "first_message_received_at",
      "null": true,
      "type": "DATETIME"
    },
    {
      "custom": false,
      "default": null,
      "display": "Última Mensagem Enviada Em",
      "is_private": false,
      "name": "last_message_sent_at",
      "null": true,
      "type": "DATETIME"
    },
    {
      "custom": false,
      "default": null,
      "display": "Última Mensagem Recebida Em",
      "is_private": false,
      "name": "last_message_received_at",
      "null": true,
      "type": "DATETIME"
    },
    {
      "custom": false,
      "default": null,
      "display": "Optou por Participar Em",
      "is_private": false,
      "name": "opted_in_at",
      "null": true,
      "type": "DATETIME"
    },
    {
      "custom": false,
      "default": null,
      "display": "ID do WhatsApp",
      "is_private": true,
      "name": "whatsapp_id",
      "null": true,
      "type": "STRING"
    },
    {
      "custom": false,
      "default": false,
      "display": "Está Bloqueado",
      "is_private": false,
      "name": "is_blocked",
      "null": false,
      "type": "BOOLEAN"
    }
  ],
  "uuid": "d4deddbf-9cca-4e26-ab55-9b6653da1325",
  "version": "0.0.1-alpha"
}

Criando Novos Campos no Perfil de Contato​

Para criar campos adicionais, envie uma solicitação HTTP POST para /v1/contacts/schemas. Isso criará uma nova definição de esquema com um novo uuid.

A partir desse ponto, a Turn.io continuará retornando contatos de acordo com esquemas anteriores, mas permitirá apenas a escrita de contatos de acordo com o esquema criado mais recentemente.

cuidado

É responsabilidade do client da API migrar os detalhes do perfil de contato entre alterações de esquema.

curl -X POST https://whatsapp.turn.io/v1/contacts/schemas \
    -H 'Authorization: Bearer token' \
    -H 'Accept: application/vnd.v1+json' \
    -H 'Content-Type: application/json' \
    -d '{
        "version": "0.0.1-alpha",
        "fields": [{
            "name": "consent",
            "display": "Consentimento Dado",
            "type": "BOOLEAN",
            "default": false,
            "is_private": true
        }, {
            "name": "gender",
            "display": "Gênero",
            "type": "ENUM",
            "null": false,
            "is_private": false,
            "default": "UNDISCLOSED",
            "enum": [
                {"value": "MALE", "display": "Masculino"},
                {"value": "FEMALE", "display": "Feminino"},
                {"value": "OTHER", "display": "Outro"},
                {"value": "UNDISCLOSED", "display": "Não Informado"}
            ]
        }]
    }'

> {
    "version": "0.0.1-alpha",
    "uuid": "<o-novo-uuid-do-esquema>",
    "fields": [{
        "name": "consent",
        "display": "Consentimento Dado",
        "type": "BOOLEAN",
        "default": false,
        "is_private": true
    }, {
        "name": "gender",
        "display": "Gênero",
        "type": "ENUM",
        "null": false,
        "is_private": false,
        "default": "UNDISCLOSED",
        "enum": [
            {"value": "MALE", "display": "Masculino"},
            {"value": "FEMALE", "display": "Feminino"},
            {"value": "OTHER", "display": "Outro"},
            {"value": "UNDISCLOSED", "display": "Não Informado"}
            ]
        }]
    }

A resposta é o esquema com o valor uuid identificando o esquema na payload.

Os tipos de campo suportados são:

  • DATETIME, restrito a timestamps formatados no padrão ISO8601 no fuso horário UTC.
  • BOOLEAN, restrito aos tipos booleanos JSON true e false.
  • STRING
  • FLOAT
  • INTEGER
  • ENUM, que requer um parâmetro adicional enum especificando a lista de valores permitidos.
  • LOCATION, que espera um objeto {"latitude": ..., "longitude": ...}.

Todos os campos podem ser configurados para aceitar valores null especificando "null": true ou "null": false.

A única exceção é o tipo de campo BOOLEAN.

O campo BOOLEAN exige um valor default definido como true ou false e não pode ser configurado para permitir valores null.

Todos os campos devem fornecer um valor default, que pode ser null se "null": true for especificado, com exceção dos campos BOOLEAN.

O parâmetro display é o nome amigável do campo.

O parâmetro name deve estar em letras minúsculas, começar com uma letra e conter apenas caracteres alfanuméricos minúsculos e sublinhados.

O parâmetro enum aceita apenas uma lista de opções. As opções são objetos que possuem campos value e display. O campo value deve estar em letras maiúsculas, começar com uma letra e conter apenas caracteres alfanuméricos maiúsculos ou underscores.

Para recuperar um esquema anterior, faça uma solicitação HTTP GET para o endpoint /v1/contacts/schemas/<uuid>.

Obtendo um Perfil de Contato​

Para obter os detalhes do perfil de um contato, faça uma chamada para o endpoint /v1/contacts/<wa-id>/profile.

curl https://whatsapp.turn.io/v1/contacts/27123456789/profile \
    -H 'Authorization: Bearer token' \
    -H 'Accept: application/vnd.v1+json'

> '{
    "version": "0.0.1-alpha",
    "schema": "<o-uuid-do-esquema>",
    "generation": 0,
    "fields": {
        "language": "ENG",
        "date_of_birth": null,
        "age": 2,
        "consent": false,
        "location": null,
        "name": null,
        "risk_profile": 2.0,
        "surname": null,
        "birthday": null,
        "opted_in": false,
        "opted_in_at": null,
        "whatsapp_id": null,
        "whatsapp_profile_name": null
    }
}'
info

Por favor, note que um campo recém-criado só aparecerá no perfil de um contato se seu valor tiver sido explicitamente definido ou atualizado. Valores padrão para novos campos não são automaticamente incluídos no perfil do contato. Por exemplo, se um campo de contato for referenciado, mas não tiver sido explicitamente definido, o valor padrão desse campo será exibido sempre que for referenciado. No entanto, ao consultar os campos de contato via o endpoint /v1/contacts/{wa_number}/profile, a resposta incluirá apenas os campos que foram explicitamente persistidos nos dados do contato. Novos campos criados na interface do usuário não aparecerão na resposta, a menos que seus valores tenham sido atualizados e salvos.

Para recuperar um perfil de contato para um esquema anterior, forneça o uuid do esquema como um parâmetro de consulta:

curl "https://whatsapp.turn.io/v1/contacts/27123456789/profile?schema=<o-uuid-do-esquema>" \
    -H 'Authorization: Bearer token' \
    -H 'Accept: application/vnd.v1+json'

> '{
    "version": "0.0.1-alpha",
    "schema": "<o-uuid-do-esquema>",
    "generation": 0,
    "fields": {
        "language": "ENG",
        "date_of_birth": null,
        "age": 2,
        "consent": false,
        "location": null,
        "name": null,
        "risk_profile": 2.0,
        "surname": null,
        "birthday": null,
        "opted_in": false,
        "opted_in_at": null,
        "whatsapp_id": null,
        "whatsapp_profile_name": null
    }
}'

O campo generation é automaticamente incrementado em 1 para cada alteração feita no perfil do contato.

Substituir um Perfil de Contato​

Para substituir os detalhes completos do perfil de um contato, faça uma chamada HTTP PUT para o endpoint /v1/contacts/<wa-id>/profile.

curl -X PUT https://whatsapp.turn.io/v1/contacts/27123456789/profile \
    -H 'Authorization: Bearer token' \
    -H 'Accept: application/vnd.v1+json' \
    -H 'Content-Type: application/json' \
    -d '{"name": "Fizbo"}'

> '{
    "version": "0.0.1-alpha",
    "generation": 1,
    "schema": "<o-uuid-do-esquema>",
    "fields": {
        "language": null,
        "date_of_birth": null,
        "age": 0,
        "consent": false,
        "location": null,
        "name": "Fizbo",
        "risk_profile": 0.0,
        "surname": null,
        "birthday": null,
        "opted_in": false,
        "opted_in_at": null,
        "whatsapp_id": null,
        "whatsapp_profile_name": null
    }
}'
info

Por favor, note que as atualizações de perfis de contato serão sempre validadas de acordo com o esquema mais recente.

Atualizar um Perfil de Contato​

Para atualizar parcialmente um perfil de contato, faça uma chamada HTTP PATCH para o endpoint /v1/contacts/<wa-id>/profile fornecendo apenas os campos que precisam ser atualizados.

curl -X PATCH https://whatsapp.turn.io/v1/contacts/27123456789/profile \
    -H 'Authorization: Bearer token' \
    -H 'Accept: application/vnd.v1+json' \
    -H 'Content-Type: application/json' \
    -d '{"name": "Fizbo"}'

> '{
    "version": "0.0.1-alpha",
    "generation": 2,
    "schema": "<o-uuid-do-esquema>",
    "fields": {
        "language": "ENG",
        "date_of_birth": null,
        "age": 2,
        "consent": false,
        "location": null,
        "name": "Fizbo",
        "risk_profile": 2.0,
        "surname": null,
        "birthday": null,
        "opted_in": false,
        "opted_in_at": null,
        "whatsapp_id": null,
        "whatsapp_profile_name": null
    }
}'
info

Por favor, note que atualizações parciais de perfis de contato serão sempre validadas de acordo com o esquema mais recente.

Redefinir um Perfil de Contato​

Para redefinir todos os detalhes do perfil de um contato para os padrões do esquema, faça uma chamada HTTP DELETE para o endpoint /v1/contacts/<wa-id>/profile.

cuidado

Por favor, note que esse comportamento excluirá o perfil do contato, redefinindo todos os valores para seus padrões ou para null. Se você deseja excluir o próprio Contato, bem como o perfil do contato, utilize o endpoint de exclusão de Chat.

$ curl -X DELETE https://whatsapp.turn.io/v1/contacts/27123456789/profile \
    -H 'Authorization: Bearer token' \
    -H 'Accept: application/vnd.v1+json' \
    -H 'Content-Type: application/json'
> '{}'

Importar Perfis de Contato via CSV​

Para importar informações de contato em massa, você pode fazer o upload de um arquivo CSV com todos os detalhes usando o endpoint da API /v1/contacts.

Os dados importados do arquivo CSV são regidos pelo esquema de contato definido usando a API de Perfil de Contato.

O arquivo CSV fornecido deve ter uma coluna chamada urn, que contém o número de telefone do contato que você deseja criar ou atualizar. Se já existir um perfil de contato para o número de telefone informado, ele será atualizado com os campos fornecidos. Caso contrário, será criado um novo perfil com os campos fornecidos.

Os valores das colunas substituirão os valores existentes dos contatos no banco de dados. Quaisquer outros valores de campos de contato permanecerão inalterados.

urn,name,surname,age
+271234567890,Peter,Parker,21
+271234567891,Peter,Barker,22
+271234567892,Peter,Porker,19
+271234567893,Spider,Ham,20

Para cada um desses contatos, a importação verificará um perfil existente com o URN fornecido e atualizará os campos. Os campos são convertidos para os tipos correspondentes no perfil de contato e retornará um erro se o campo não puder ser convertido.

nota

Observe que qualquer campo fornecido no CSV que não seja conhecido pelo esquema de contato será ignorado.

Os contatos são importados imediatamente no banco de dados principal e estarão disponíveis para mensagens. Eles são indexados de forma assíncrona no banco de dados de pesquisa secundário, podendo levar um ou dois minutos para estarem disponíveis em Reminders e Gatilhos após a conclusão da importação.

Esta API transmitirá o resultado da importação em tempo real como uma resposta formatada em CSV:

$ curl \
    -X POST
    -H 'Content-Type: text/csv' \
    -H 'Authorization: Bearer token' \
    --data-binary 'urn,name,surname
+27123456789,spider,ham
+27123456790,peter,parker
' https://whatsapp.turn.io/v1/contacts
> 'urn,name,surname
+27123456789,spider,ham
+27123456790,peter,parker'

Relatórios de erro para tipos incompatíveis​

Se tentarmos enviar um CSV com dados inválidos, a API retornará o erro inline com o prefixo ERROR na posição do campo em questão.

$ curl \
    -X POST \
    -H 'Content-Type: text/csv' \
    -H 'Authorization: Bearer token' \
    --data-binary 'urn,name,surname,opted_in  
+27123456789,peter,parker,"yes"
' https://whatsapp.turn.io/v1/contacts  
> "+27123456789,,,ERROR: não foi possível converter o valor 'yes' para booleano"

Colunas desconhecidas​

Se o próprio URN estiver com formato incorreto, o erro será exibido na segunda coluna.

Qualquer coluna fornecida no CSV que não possa ser mapeada para um campo conhecido será descartada e não será incluída na resposta.

$ curl \
    -X POST \
    -H 'Content-Type: text/csv' \
    -H 'Authorization: Bearer token' \
    --data-binary 'urn,name,surname,unknown_field  
+27123456789,peter,parker,unknown_field_value
' https://whatsapp.turn.io/v1/contacts  
> 'urn,name,surname  
+27123456789,peter,parker'

Conversão para tipos de campos de contato​

Todos os valores conhecidos são transmitidos de volta após o parsing e a conversão de tipo, representando as representações internas desses valores na Turn.io. O URN será normalizado no formato E164 e a string "true" será convertida para o booleano true para o campo opted_in.

$ curl \
    -X POST \
    -H 'Content-Type: text/csv' \
    -H 'Authorization: Bearer token' \
    --data-binary 'urn,name,surname,opted_in
+27123456789,peter,parker,"true"
' https://whatsapp.turn.io/v1/contacts  
> '+27123456789,peter,parker,true'

Limitações de tamanho do arquivo​

Atualmente, o limite da API permite arquivos de até 1 Megabyte. Se você precisar enviar mais dados de contatos do que podem ser representados em 1 Megabyte, será necessário dividir os dados em arquivos CSV separados, cada um com seu próprio header.

[Descontinuado] Busca de Perfis de Contato​

O endpoint em /v1/export/contacts/details foi descontinuado. Para exportar dados de contato, use a API de Exportação de Dados.

[Descontinuado] Verificação de Status do WhatsApp​

cuidado

A API de Contatos original on-premisse foi reformulada a partir da versão v2.43 da API do WhatsApp Business. Ela não fornece mais informações de status sobre um número de telefone.

As respostas desse endpoint não retornam mais um status 'inválido'. Um status 'válido' e um wa_id serão fornecidos para todas as solicitações, independentemente de o número de telefone estar conectado a uma conta do WhatsApp. Não há garantia de que o wa_id retornado seja válido. Essas mudanças se aplicam tanto para respostas diretas quanto para respostas via webhook em chamadas não bloqueantes. O WhatsApp continuará retornando as mesmas respostas 'processing' e 'failed', como faz atualmente.

A implementação original da API permanece ativa, mas não está mais documentada e será removida completamente no futuro.