13 de septiembre: cambios en el punto final de la API de datos de contacto

Nathan Begbie Actualizado por Nathan Begbie

Si está utilizando nuestra API de exportación de datos para recuperar detalles de contacto, debe conocer los próximos cambios.

Para corregir una discrepancia entre los contactos en la API de exportación de datos de mensajes y los contactos en la API de detalles de contacto, estamos actualizando la forma en que se devuelven los detalles de contacto en Exportación de datos API.

¿Cuándo se producirá el cambio?

Estos cambios se implementarán el jueves 22 de septiembre de 2022 para quienes operan en whatsapp.turn.io. Para aquellos en nubes privadas, pueden esperar tener estos cambios el jueves 29 de septiembre.

¿Qué es importante saber?

Hay 3 cambios clave que debes tener en cuenta.

1. Algunos nombres de campos se están eliminando o cambiando

Dado que solo devolveremos los datos más recientes de un contacto, eliminaremos los siguientes campos de cada objeto de datos JSON que represente un contacto:

  • contact_id
  • contact_schema_id
  • generación
  • último
2. La clave fields: {} está cambiando a details: {}

En lugar de una clave fields: {}, cambiamos esto a details: {} para el objeto que contiene los detalles de un contacto. Esto hace que nuestra API esté más en línea con nuestra integración de BigQuery.

Lo que solía ser:

{
 "data": [
 {
 "fields": {
 ...
 "language": "eng",
 "whatsapp_id": "2712345678",
 ...
 },
 },
 ...
 ],
 ...
}

Qué está cambiando a:

{
 "datos": [
 {
 "detalles": {
 ...
 "idioma": "ing",
 "whatsapp_id": "2712345678",
 ...
 },
 },
 ...
 ],
 ...
}

De manera similar, las reglas de limpieza anteriormente requerían que se usara el patrón fields.<detail_name> (por ejemplo, "fields.surname": {"type": "hash"}) . En su lugar, usaremos details.<detail_name> (por ejemplo, "details.surname": {"type": "hash"} )

3. Debe paginar los contactos de manera diferente

Estamos actualizando la API de contacto para devolver solo los datos más recientes de un contacto, en el momento en que se actualizó por última vez.

La exportación de datos de detalles de contacto difiere en comportamiento del punto final de exportación de mensajes en una manera crucial: los contactos y los campos de contactos cambiarán con el tiempo, mientras que los mensajes se crean una vez y no se actualizan. Esto significa que una vez que un mensaje se ha registrado en la base de datos, sus propiedades no cambian. Por lo tanto, paginamos por el inserted_at campo para mensajes.

Sin embargo, los contactos y sus campos cambiarán con el tiempo. Por ejemplo, si creamos un campo personalizado llamado current_ Savings que actualizamos a medida que un contacto aumenta o disminuye sus ahorros. Si paginamos por inserted_at, necesitaría paginar todos los contactos cada vez para obtener datos actualizados. En su lugar, paginamos según el momento en que se actualizaron los contactos. Esto significa que el comportamiento esperado sería solicitar datos de forma diaria o semanal durante un período de tiempo de un día o una semana, respectivamente. Esto incluirá toda la información de actualización desde la última vez que solicitó los datos de contacto.

Si tiene un trabajo cron existente que ingiere datos, necesitará solicitar datos solo para los períodos de tiempo sobre los que aún no se ha paginado.

Un ejemplo de cómo obtener detalles actualizados

Imagine que tenemos un solo usuario que nos envía mensajes (Bob) y un campo de perfil personalizado llamado `current_ Savings`. El lunes 12 de septiembre de 2022, nos envían un mensaje para decirnos que sus ahorros actuales son de $100.

Si ejecutamos lo siguiente el martes (13), podríamos consultar estos datos de esta manera:

# solicitar un cursor para los datos
$ curl -X POST "https://whatsapp.turn.io/v1/data/contacts/cursor" \
 -H "Autorización: token al portador" \
 -H "Tipo de contenido: aplicación/json" \
 -H "aceptar: application/vnd.v1+json"
 -d '
 {
 # inicio del lunes 12
 "desde": "2022-09-12T00:00:00.000Z",
 # por un periodo de 24 horas
 "hasta": "2022-09-13T00:00:00.000Z"
 }
> {
 "cursor": "an-example-cursor-1234",
 "expires_at": "2022-09-14T17:47:18.318218Z"
}
# solicitar los datos usando el cursor dado
$ curl -X GET "https://whatsapp.turn.io/v1/data/contacts/cursor/an-example-cursor-1234" \
 -H 'Autorización: Token al portador' \
 -H "Aceptar: aplicación/vnd.v1+json" \
> {
 "datos": [
 {
 "detalles": {
 "cumpleaños": "1988-06-14T18:15:35.873852Z",
 "idioma": "eng",
 "ubicación": nulo,
 "nombre": "bob",
 "opted_in": falso,
 "opted_in_at": nulo,
 "apellido": nulo,
 "whatsapp_id": "44623456700",
 "nombre_perfil_whatsapp": "bob",
 "ahorro_actual": 100
 },
 "id": 1,
 "insertado_en": "20222-09-12T08:30:00.000Z",
 "number_id": 1,
 "actualizado_en": "20222-09-12T08:30:00.000Z",
 "uuid": "f6c4e666-81ad-430e-aea5-1ba33e6f4c35"
 }
 ]
}

¡Genial! Entonces tenemos los datos y podemos almacenarlos en nuestro lago de datos o base de datos de análisis.

Ahora, imagina que Bob vuelve a enviar un mensaje el martes para decir que sus ahorros han aumentado a $120. Si solicitamos los datos para el mismo período de tiempo (lunes), el miércoles 14, ya no recibiremos ningún dato para Bob:

# solicitar un cursor para los datos
$ curl -X POST "https://whatsapp.turn.io/v1/data/contacts/cursor" \
 -H "Autorización: Token al portador" \
 -H "Tipo de contenido: aplicación/json" \
 -H "aceptar: application/vnd.v1+json"
 -d '
 {
 # inicio del lunes 12
 "desde": "2022-09-12T00:00:00.000Z",
 # por un periodo de 24 horas
 "hasta": "2022-09-13T00:00:00.000Z"
 }
> {
 "cursor": "otro-cursor-de-ejemplo-5678",
 "expires_at": "2022-09-16T17:48:18.763987Z"
}
# solicitar los datos
curl -X GET "https://whatsapp.turn.io/v1/data/contacts/cursor/an-example-cursor-1234" \
 -H 'Autorización: Token al portador' \
 -H "Aceptar: aplicación/vnd.v1+json" \
> {
 "datos": []
}

En cambio, si queremos datos actualizados, debemos solicitar los datos del día siguiente:

# solicitar un cursor para los datos
$ curl -X POST "https://whatsapp.turn.io/v1/data/contacts/cursor" \
 -H "Autorización: Token al portador" \
 -H "Tipo de contenido: aplicación/json" \
 -H "aceptar: application/vnd.v1+json"
 -d '
 {
 # inicio del martes 13
 "desde": "2022-09-13T00:00:00.000Z",
 # por un período de 24 horas
 "hasta": "2022-09-14T00:00:00.000Z"
 }
> {
 "cursor": "todavía-otro-cursor-de-ejemplo-9876",
 "expires_at": "2022-09-16T17:48:18.763987Z"
}
# solicitar los datos usando el cursor dado
$ curl -X OBTENER "https://whatsapp.turn.io/v1/data/contacts/cursor/yet-another-example-cursor-9876" \
 -H 'Autorización: Token al portador' \
 -H "Aceptar: aplicación/vnd.v1+json" \
> {
 "datos": [
 {
 "detalles": {
 "cumpleaños": "1988-06-14T18:15:35.873852Z",
 "idioma": "eng",
 "ubicación": nulo,
 "nombre": "bob",
 "opted_in": falso,
 "opted_in_at": nulo,
 "apellido": nulo,
 "whatsapp_id": "44623456700",
 "whatsapp_profile_name": "bob",
 # ¡nota el cambio en el valor aquí!
 "ahorros_actuales": 120
 },
 "id": 1,
 "insertado_en": "20222-09-12T08:30:00.000Z",
 "number_id": 1,
 "actualizado_en": "20222-09-13T10:00:00.000Z",
 "uuid": "f6c4e666-81ad-430e-aea5-1ba33e6f4c35"
 }
 ]
}

Nota: No debería necesitar solicitar los datos utilizando el intervalo de tiempo del número para obtener datos de contacto actualizados, a menos que los solicite por primera vez. 

Vea más llamadas de ejemplo en la documentación de API.

¿Cómo lo hicimos?

15 de septiembre de 2022: los mensajes más cortos son mejores

7 de septiembre de 2022: mejoras en la pila

Contacto