13 de setembro: alterações no endpoint da API de detalhes de contato

Nathan Begbie Atualizado por Nathan Begbie

Se você estiver usando nossa API de exportação de dados para recuperar detalhes de contato, você deve saber sobre mudanças futuras.

Para corrigir uma incompatibilidade entre os contatos na API de exportação de dados de mensagens e os contatos na API de detalhes de contato, estamos atualizando a forma como os dados de contato são retornados na Exportação de dados API.

Quando a mudança acontecerá?

Essas mudanças serão implementadas na quinta-feira, 22 de setembro de 2022, para aqueles que operam no whatsapp.turn.io. Para aqueles que usam nuvens privadas, essas mudanças serão esperadas na quinta-feira, 29 de setembro.

O que é importante saber?

Há três mudanças importantes que você deve observar.

1. Alguns nomes de campos estão sendo removidos ou alterados

Como retornaremos apenas os dados mais recentes de um contato, removemos os seguintes campos de cada objeto de dados JSON que representa um contato:

  • contact_id
  • contact_schema_id
  • geração
  • mais recente
2. A chave fields: {} está mudando para details: {}

Em vez de uma chave fields: {}, mudamos para details: {} para o objeto que contém os detalhes de um contato. Isso deixa nossa API mais alinhada com nossa integração com o BigQuery.

O que costumava ser:

{
 "dados": [
 {
 "campos": {
 ...
 "idioma": "eng",
 "whatsapp_id": "2712345678",
 ...
 },
 },
 ...
 ],
 ...
}

Para que está mudando:

{
 "dados": [
 {
 "detalhes": {
 ...
 "idioma": "eng",
 "whatsapp_id": "2712345678",
 ...
 },
 },
 ...
 ],
 ...
}

Da mesma forma, as regras de depuração anteriormente exigiam que se usasse o padrão fields.<detail_name> (por exemplo, "fields.surname": {"type": "hash"}) . Em vez disso, usaremos details.<detail_name> (por exemplo, "details.surname": {"type": "hash"} )

3. Você precisa paginar os Contatos de maneira diferente

Estamos atualizando a API de Contatos para retornar apenas os dados mais recentes de um contato, no momento em que ele foi atualizado pela última vez.

A exportação de dados de detalhes de contato difere em comportamento do endpoint de exportação de mensagens de uma maneira crucial: os contatos e os campos de contatos mudarão ao longo do tempo, pois as mensagens são criadas uma vez e não são atualizadas. Isso significa que depois que uma mensagem é registrada no banco de dados, suas propriedades não mudam. Assim, paginamos pelo inserted_at campo para mensagens.

No entanto, os contatos e seus campos mudarão com o tempo. Por exemplo, se criamos um campo personalizado chamado current_ savings que atualizamos conforme um contato aumenta ou diminui suas economias. Se paginássemos por inserted_at, você precisaria paginar todos os contatos sempre para obter dados atualizados. Em vez disso, paginamos quando os contatos foram atualizados. Isso significa que o comportamento esperado seria solicitar dados diariamente ou semanalmente por um período de um dia ou uma semana, respectivamente. Isso incluirá todas as informações de atualização desde a última vez que você solicitou os dados de contato.

Se você tiver um cron job que ingere dados, ele precisará solicitar dados apenas para os períodos de tempo que ainda não foram paginados.

Um exemplo de como obter detalhes atualizados

Imagine que temos apenas um único usuário que nos envia mensagens (Bob) e um campo de perfil personalizado chamado `current_ savings`. Na segunda-feira, 12 de setembro de 2022, eles nos enviaram uma mensagem dizendo que suas economias atuais são de US$ 100.

Se executarmos o seguinte na terça-feira (13), poderemos consultar esses dados da seguinte forma:

# solicite um cursor para os dados
$ curl -X POST "https://whatsapp.turn.io/v1/data/contacts/cursor" \
 -H "Autorização: token do portador" \
 -H "Tipo de conteúdo: aplicativo/json" \
 -H "accept: application/vnd.v1+json"
 -d '
 {
 # início de segunda-feira, dia 12
 "de": "2022-09-12T00:00:00.000Z",
 # por um período de 24 horas
 "até": "2022-09-13T00:00:00.000Z"
 }
> {
 "cursor": "an-example-cursor-1234",
 "expires_at": "2022-09-14T17:47:18.318218Z"
}
# solicita os dados usando o cursor fornecido
$ curl -X OBTER "https://whatsapp.turn.io/v1/data/contacts/cursor/an-example-cursor-1234" \
 -H 'Autorização: token do portador' \
 -H "Aceitar: application/vnd.v1+json" \
> {
 "dados": [
 {
 "detalhes": {
 "aniversário": "1988-06-14T18:15:35.873852Z",
 "idioma": "eng",
 "localização": null,
 "nome": "bob",
 "opted_in": false,
 "opted_in_at": null,
 "sobrenome": null,
 "whatsapp_id": "44623456700",
 "nome_do_perfil_whatsapp": "bob",
 "economia_atual": 100
 },
 "id": 1,
 "inserted_at": "20222-09-12T08:30:00.000Z",
 "número_id": 1,
 "atualizado_at": "20222-09-12T08:30:00.000Z",
 "uuid": "f6c4e666-81ad-430e-aea5-1ba33e6f4c35"
 }
 ]
}

Ótimo! Portanto, temos os dados e podemos armazená-los em nosso data lake ou banco de dados analítico.

Agora, imagine que Bob envie uma mensagem novamente na terça-feira, para dizer que suas economias aumentaram para US$ 120. Se solicitarmos os dados para o mesmo período (segunda-feira), na quarta-feira, dia 14, não receberemos mais nenhum dado de Bob:

# request a cursor for the data
$ curl -X POST "https://whatsapp.turn.io/v1/data/contacts/cursor" \
 -H "Autorização: token do portador" \
 -H "Tipo de conteúdo: aplicativo/json" \
 -H "accept: application/vnd.v1+json"
 -d '
 {
 # início de segunda-feira, dia 12
 "de": "2022-09-12T00:00:00.000Z",
 # por um período de 24 horas
 "até": "2022-09-13T00:00:00.000Z"
 }
> {
 "cursor": "another-example-cursor-5678",
 "expires_at": "2022-09-16T17:48:18.763987Z"
}
# solicitar os dados
curl -X OBTENHA "https://whatsapp.turn.io/v1/data/contacts/cursor/an-example-cursor-1234" \
 -H 'Autorização: token do portador' \
 -H "Aceitar: application/vnd.v1+json" \
> {
 "dados": []
}

Em vez disso, se quisermos dados atualizados, devemos solicitar os dados do dia seguinte:

# solicitar um cursor para os dados
$ curl -X POST "https://whatsapp.turn.io/v1/data/contacts/cursor" \
 -H "Autorização: token do portador" \
 -H "Tipo de conteúdo: aplicativo/json" \
 -H "accept: application/vnd.v1+json"
 -d '
 {
 # início de terça-feira, dia 13
 "de": "2022-09-13T00:00:00.000Z",
 # por um período de 24 horas
 "até": "2022-09-14T00:00:00.000Z"
 }
> {
 "cursor": "yet-another-example-cursor-9876",
 "expires_at": "2022-09-16T17:48:18.763987Z"
}
# solicita os dados usando o dado cursor
$ curl -X GET "https://whatsapp.turn.io/v1/data/contacts/cursor/yet-another-example-cursor-9876" \
 -H 'Autorização: token do portador' \
 -H "Aceitar: application/vnd.v1+json" \
> {
 "dados": [
 {
 "detalhes": {
 "aniversário": "1988-06-14T18:15:35.873852Z",
 "idioma": "eng",
 "localização": null,
 "nome": "bob",
 "opted_in": false,
 "opted_in_at": null,
 "sobrenome": null,
 "whatsapp_id": "44623456700",
 "whatsapp_profile_name": "bob",
 # observe a mudança no valor aqui!
 "economia_atual": 120
 },
 "id": 1,
 "inserted_at": "20222-09-12T08:30:00.000Z",
 "número_id": 1,
 "atualizado_em": "20222-09-13T10:00:00.000Z",
 "uuid": "f6c4e666-81ad-430e-aea5-1ba33e6f4c35"
 }
 ]
}

Observação: você não deve precisar solicitar os dados usando o intervalo de tempo do número para obter dados de contato atualizados, a menos que esteja solicitando pela primeira vez tempo. 

Veja mais exemplos de chamadas na documentação da API.

Esse artigo foi útil?

15 de setembro de 2022: Mensagens mais curtas são melhores

7 de setembro de 2022: melhorias na pilha

Contato