Referencia de la API
Hellotext ofrece una poderosa API REST diseñada para la felicidad del desarrollador. Nos esforzamos constantemente en mantener todos los recursos y acciones simples y consistentes.
Todas las respuestas tienen formato y se devuelven en JSON.
https://api.hellotext.com
Autenticación
Todas las solicitudes a la API deben ser autenticadas. La autenticación se realiza enviando un token con cada solicitud a la API.
Puede crear y administrar tus tokens de autorización desde la sección de Ajustes. Todos los tokens de autorización son específicos del negocio desde el cual se crearon.
Para autenticar, asegúrate de incluir un encabezado de autorización con el formato Authorization: Bearer {token}. Reemplaza el token con el token de autorización.
curl https://api.hellotext.com/v1/profiles \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Errores
Hellotext utiliza códigos de respuesta HTTP convencionales para indicar el estado de una solicitud. Cuando una solicitud es válida pero no se completa como se esperaba, respondemos con un un error 422 y un objeto JSON de errores objeto, incluida una colección de errores que incluye el tipo y la descripción.
{
"errors": [
{
"type": "parameter_missing",
"message": "This parameter is required.",
"parameter": "name"
}
]
}
Paginación
Todas las colecciones de recursos de primer nivel se pueden paginar. Las colecciones se ordenan por fecha de creación, mostrando primero los objetos más recientes y limitando los resultados a 25 de forma predeterminada. Para ajustar la cantidad de resultados, puedes utilizar el parámetro limit.
Dado que nuevos objetos serán creados, para mantener el orden consistente en la paginación, puedes obtener el siguiente conjunto de resultados a partir del último ID de la colección anterior utilizando el parámetro starting_after. Esto incluye el siguiente conjunto de resultados después de (excluyendo) el id proporcionado. Esto también se llama paginación vectorial.
También puedes lograr lo contrario y recuperar todos los resultados hasta el identificado dado utilizando el parámetro ending_before.
curl -G https://api.hellotext.com/v1/profiles \
-d starting_after="BvYeyVYz" \
-d limit=10 \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Perfiles
Los clientes se representan como perfiles. Cada objeto de perfil representa las características de cada cliente y su historial de interacciones con el negocio.
Cada perfil acepta cualquier número de propiedades como números de teléfono, correos electrónicos, direcciones geo-localizadas, atributos personales como cumpleaños, sexo o cualquier otro caso personalizado.
-
POST
v1/profiles
-
GET
v1/profiles/:id
-
PATCH
v1/profiles/:id
-
DELETE
v1/profiles/:id
-
GET
v1/profiles
-
POST
v1/profiles/:id/subscribe
-
POST
v1/profiles/:id/unsubscribe
-
POST
v1/profiles/:id/verify
-
DELETE
v1/profiles/:id/verify
El objeto de perfil
email
phone, enumerados en formato e164.
unconfirmed
Defecto
subscribed
unsubscribed
{
"id": "MzYwlE50",
"type": "profile",
"blocked": false,
"created_at": 1665684173,
"emails": [
"will.e@acme.com"
],
"first_name": "Will E",
"last_name": "Coyote",
"lists": [
{
"id": "zN4Xx4Km",
"type": "list",
"name": "Greens",
"created_at": 1665684173
}
],
"phones": [
"+59898000001"
],
"properties": [
{
"id": "MQNKalb7",
"kind": "address",
"value": {
"city": "Montevideo",
"country": "UY",
"latitude": "-0.349044168e2",
"longitude": "-0.561370421e2",
"notes": null,
"postal_code": "11300",
"region": "Departamento de Montevideo",
"street": {
"name": "Av. Luis Alberto de Herrera",
"number": "1248"
},
"subregion": "CH"
}
},
{
"id": "MQNKalb7",
"kind": "birthday",
"name": null,
"value": {
"day": 3,
"month": 11,
"year": 1985
}
},
{
"id": "MQNKalb7",
"kind": "email",
"name": null,
"value": "will.e@acme.com",
"verified": true
},
{
"id": "MQNKalb7",
"kind": "phone",
"name": null,
"value": "+59898000001",
"verified": true
},
{
"id": "MQNKalb7",
"kind": "gender",
"name": null,
"value": "male"
}
],
"state": "subscribed",
"verified_emails": [
"will.e@acme.com"
],
"verified_phones": [
"+59898000001"
]
}Crear un perfil
Crea un nuevo perfil.
address predeterminada. Puede pasar un objeto de dirección u, opcionalmente, proporcionar una cadena como address[suggest]. Al proporcionar la cadena de sugerencia, deconstruiremos la cadena y construiremos un objeto address a partir de ella.
address con el nombre declarado entre corchetes. Por ejemplo, address[work]= configurará la dirección para la propiedad address con el nombre work. La propiedad se creará automáticamente para el perfil actual si aún no existe.
email con el nombre declarado entre corchetes. Por ejemplo, email[trabajo]= configurará el correo electrónico para la propiedad email con el nombre trabajo. La propiedad se creará automáticamente para el perfil actual si aún no existe.
phone predeterminada. Espera un número en formato e164 o un número en formato local que se convertirá a e164 utilizando el país comercial como prefijo de país.
phone con el nombre declarado entre corchetes. Por ejemplo, phone[trabajo]= configurará el teléfono para la propiedad phone con el nombre trabajo. La propiedad se creará automáticamente para el perfil actual si aún no existe.
property[Active]=true. Si la propiedad no tiene nombre, es posible hacer referencia a ella pasando su tipo como su nombre, es decir, property[gender]=male.
property[gVlpOkwJ]=MiValor.
true para suscribir al cliente en la creación del perfil. Si el cliente ya otorgó el consentimiento para recibir comunicaciones promocionales de tu marca, puedes indicarlo de esta manera. El valor predeterminado es false, lo que significa que los nuevos perfiles no se suscriben automáticamente.
curl -X POST https://api.hellotext.com/v1/profiles
-d first_name="Will E"
-d last_name="Coyote"
-d phone="+59899000001"
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "MzYwlE50"
}Obtener un perfil
Obtener un perfil existente.
curl -G https://api.hellotext.com/v1/profiles/MzYwlE50
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."Modificar un perfil
Modifica el perfil especificado con la información proporcionada.
address predeterminada. Puede pasar un objeto de dirección u, opcionalmente, proporcionar una cadena como address[suggest]. Al proporcionar la cadena de sugerencia, deconstruiremos la cadena y construiremos un objeto address a partir de ella. Proporcionar un valor vacío elimina la dirección predeterminada del perfil. Por ejemplo, address='' o address={}.
address[gVlpOkwJ]=MiValor. Pasar un valor vacío eliminará la dirección del perfil. Por ejemplo, address[gVlpOkwJ]='' eliminará la dirección con la identificación dada.
address con el nombre declarado entre corchetes. Por ejemplo, address[work]= configurará la dirección para la propiedad address con el nombre work. La propiedad se creará automáticamente para el perfil actual si aún no existe. Pasar un valor vacío eliminará la dirección del perfil. Por ejemplo, address[work]='' eliminará la dirección work del perfil.
email predeterminada. Pasar un valor vacío eliminará el correo electrónico predeterminado, por ejemplo, email='' eliminará el correo electrónico predeterminado. Si el perfil tiene otros correos electrónicos, el segundo correo electrónico se marcará como el nuevo predeterminado.
email[gVlpOkwJ]=will.e@acme.com. Pasar un valor vacío elimina el correo electrónico del perfil. Por ejemplo, email[gVlpOkwJ]='' eliminará el email del perfil.
email con el nombre declarado entre corchetes. Por ejemplo, email[trabajo]= configurará el correo electrónico para la propiedad email con el nombre trabajo. La propiedad se creará automáticamente para el perfil actual si aún no existe. Pasar un valor vacío elimina el correo electrónico del perfil. Por ejemplo, email[trabajo]='' eliminará el e-mail trabajo del perfil.
[] se va eliminar el perfil de todas las listas.
phone predeterminada. Espera un número en formato e164 o un número en formato local que se convertirá a e164 utilizando el país comercial como prefijo de país. Pasar un valor vacío eliminará el teléfono predeterminado del perfil. Por ejemplo, phone='' eliminará el teléfono predeterminado del perfil. Si el perfil tiene otros números de teléfono, el segundo número de teléfono se marca como el nuevo predeterminado
phone[gVlpOkwJ]=099888888. Pasar un valor vacío elimina el correo electrónico del perfil. Por ejemplo, phone[gVlpOkwJ]='' eliminará el phone del perfil.
phone con el nombre declarado entre corchetes. Por ejemplo, phone[trabajo]= configurará el teléfono para la propiedad phone con el nombre trabajo. La propiedad se creará automáticamente para el perfil actual si aún no existe Pasar un valor vacío elimina el teléfono del perfil. Por ejemplo, phone[trabajo]='' eliminará el teléfono trabajo del perfil.
property[Active]=true. Si la propiedad no tiene nombre, es posible hacer referencia a ella pasando su tipo como su nombre, es decir, property[gender]=male.
curl -X PATCH https://api.hellotext.com/v1/profiles/MzYwlE50
-d email="will.e@acme.com"
-d gender="male"
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "MzYwlE50",
"updated": true
}Eliminar un perfil
Elimina el perfil especificado. Eliminar un perfil significa que todas sus propiedades serán eliminadas. Las conversaciones asociadas serán preservadas. Puedes restaurar el perfil una vez más a través del panel de control o la API cambiando el estado de suscripción del perfil a subscribed.
curl -X DELETE https://api.hellotext.com/v1/profiles/MzYwlE50
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "MzYwlE50",
"type": "profile",
"deleted": true
}Listar todos los perfiles
Enumera los perfiles existentes ordenados por los más recientes. Los parámetros de paginación están disponibles en listas.
activity
Defecto
Ordenar por la última fecha de actividad del perfil. Los perfiles con actividad más reciente aparecerán primero.
alphabetically
Ordenar por apellido, nombre.
created_at
Ordenar por la fecha de creación del perfil.
curl -G https://api.hellotext.com/v1/profiles
-d limit=5
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"profiles": [
{
"id": "MzYwlE50",
"type": "profile",
"blocked": false,
"created_at": 1665684173,
"emails": [
"will.e@acme.com"
],
"first_name": "Will E",
"last_name": "Coyote",
"lists": [
{
"id": "zN4Xx4Km",
"type": "list",
"name": "Greens",
"created_at": 1665684173
}
],
"phones": [
"+59898000001"
],
"properties": [
{
"id": "MQNKalb7",
"kind": "address",
"value": {
"city": "Montevideo",
"country": "UY",
"latitude": "-0.349044168e2",
"longitude": "-0.561370421e2",
"notes": null,
"postal_code": "11300",
"region": "Departamento de Montevideo",
"street": {
"name": "Av. Luis Alberto de Herrera",
"number": "1248"
},
"subregion": "CH"
}
},
{
"id": "MQNKalb7",
"kind": "birthday",
"name": null,
"value": {
"day": 3,
"month": 11,
"year": 1985
}
},
{
"id": "MQNKalb7",
"kind": "email",
"name": null,
"value": "will.e@acme.com",
"verified": true
},
{
"id": "MQNKalb7",
"kind": "phone",
"name": null,
"value": "+59898000001",
"verified": true
},
{
"id": "MQNKalb7",
"kind": "gender",
"name": null,
"value": "male"
}
],
"state": "subscribed",
"verified_emails": [
"will.e@acme.com"
],
"verified_phones": [
"+59898000001"
]
},
"{...}",
"{...}"
]
}Suscribir un perfil
Marca un perfil como suscrito para recibir comunicaciones promocionales de tu marca.
curl -X POST https://api.hellotext.com/v1/profiles/MzYwlE50/subscribe
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "MzYwlE50",
"type": "profile",
"blocked": false,
"created_at": 1665684173,
"emails": [
"will.e@acme.com"
],
"first_name": "Will E",
"last_name": "Coyote",
"lists": [
{
"id": "zN4Xx4Km",
"type": "list",
"name": "Greens",
"created_at": 1665684173
}
],
"phones": [
"+59898000001"
],
"properties": [
{
"id": "MQNKalb7",
"kind": "address",
"value": {
"city": "Montevideo",
"country": "UY",
"latitude": "-0.349044168e2",
"longitude": "-0.561370421e2",
"notes": null,
"postal_code": "11300",
"region": "Departamento de Montevideo",
"street": {
"name": "Av. Luis Alberto de Herrera",
"number": "1248"
},
"subregion": "CH"
}
},
{
"id": "MQNKalb7",
"kind": "birthday",
"name": null,
"value": {
"day": 3,
"month": 11,
"year": 1985
}
},
{
"id": "MQNKalb7",
"kind": "email",
"name": null,
"value": "will.e@acme.com",
"verified": true
},
{
"id": "MQNKalb7",
"kind": "phone",
"name": null,
"value": "+59898000001",
"verified": true
},
{
"id": "MQNKalb7",
"kind": "gender",
"name": null,
"value": "male"
}
],
"state": "subscribed",
"verified_emails": [
"will.e@acme.com"
],
"verified_phones": [
"+59898000001"
]
}Desuscribir un perfil
Cancela la suscripción de un perfil para recibir futuras comunicaciones promocionales de tu marca.
curl -X POST https://api.hellotext.com/v1/profiles/MzYwlE50/unsubscribe
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "MzYwlE50",
"type": "profile",
"blocked": false,
"created_at": 1665684173,
"emails": [
"will.e@acme.com"
],
"first_name": "Will E",
"last_name": "Coyote",
"lists": [
{
"id": "zN4Xx4Km",
"type": "list",
"name": "Greens",
"created_at": 1665684173
}
],
"phones": [
"+59898000001"
],
"properties": [
{
"id": "MQNKalb7",
"kind": "address",
"value": {
"city": "Montevideo",
"country": "UY",
"latitude": "-0.349044168e2",
"longitude": "-0.561370421e2",
"notes": null,
"postal_code": "11300",
"region": "Departamento de Montevideo",
"street": {
"name": "Av. Luis Alberto de Herrera",
"number": "1248"
},
"subregion": "CH"
}
},
{
"id": "MQNKalb7",
"kind": "birthday",
"name": null,
"value": {
"day": 3,
"month": 11,
"year": 1985
}
},
{
"id": "MQNKalb7",
"kind": "email",
"name": null,
"value": "will.e@acme.com",
"verified": true
},
{
"id": "MQNKalb7",
"kind": "phone",
"name": null,
"value": "+59898000001",
"verified": true
},
{
"id": "MQNKalb7",
"kind": "gender",
"name": null,
"value": "male"
}
],
"state": "unsubscribed",
"verified_emails": [
"will.e@acme.com"
],
"verified_phones": [
"+59898000001"
]
}Verificar la información de contacto de un perfil
Verifica la información de contacto de un perfil para asegurar que la información haya sido verificada y evitar suplantaciones.
curl -X POST https://api.hellotext.com/v1/profiles/MzYwlE50/verify
-d phone="+598000000"
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"verified": true
}curl -X POST https://api.hellotext.com/v1/profiles/MzYwlE50/verify
-d email="will.e@acme.com"
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"verified": true
}Desverificar la información de contacto de un perfil
curl -X DELETE https://api.hellotext.com/v1/profiles/MzYwlE50/verify
-d phone="+598000000"
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"verified": false
}curl -X DELETE https://api.hellotext.com/v1/profiles/MzYwlE50/verify
-d email="will.e@acme.com"
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"verified": false
}Propiedades
Las propiedades son los atributos de perfiles como teléfono, correo electrónico, empresa, género, fecha de nacimiento y dirección.
Puedes crear propiedades personalizadas para cualquier necesidad específica simplemente eligiendo su tipo y un nombre opcional. Cada tipo de propiedad espera su valor con una estructura específico. Para más información, revisa detallado de cada formato a continuación.
Una vez que creadas, las nuevas propiedades están disponibles de inmediato en todos los perfiles nuevos y existentes.
phone, email, mercadolibre propiedades están agrupadas juntas y mostradas antes de todas las propeidades otras, en el orden mencionado. Por lo tanto, su posición refleja solo el orden dentro de su propia especie.
-
POST
v1/properties
-
GET
v1/properties/:id
-
PATCH
v1/properties/:id
-
DELETE
v1/properties/:id
-
GET
v1/properties
El objeto de propiedad
false. La singularidad de la propiedad determina si varios perfiles pueden tener el mismo valor. Las propiedades únicas aseguran que no haya dos perfiles con el mismo valor. Esto es útil en casos en los que deseas que un solo perfil tenga un valor específico en un momento determinado. Aparte de los tipos mencionados a continuación, todos los demás tipos pueden configurarse como únicos, las actualizaciones a estas propiedades que apuntan al atributo
unique son ignoradas.
birthday
checkbox
date
gender
list
tags
{
"id": "OBYBnY69",
"type": "property",
"created_at": 1665684173,
"kind": "text",
"name": "My Property",
"position": 8,
"profile": null,
"unique": false
}Clases de propiedades
Las propiedades tienen diferentes formatos para sus valores dependiendo de su clase, expresado con el atributo kind.
Cada tipo de kind espera un formato específico como su valor. Consulte la descripción de cada uno a continuación.
Los valores de las propiedades siempre se establecen desde el objeto de perfil.
Representa una dirección asociada a un perfil. Puede ayudar a realizar un seguimiento de las direcciones de los clientes. El uso de esta propiedad facilita la segmentación de clientes en regiones, calles o países específicos.
{
"id": "MQNKalb7",
"kind": "address",
"value": {
"city": "Montevideo",
"country": "UY",
"latitude": "-0.349044168e2",
"longitude": "-0.561370421e2",
"notes": null,
"postal_code": "11300",
"region": "Departamento de Montevideo",
"street": {
"name": "Av. Luis Alberto de Herrera",
"number": "1248"
},
"subregion": "CH"
}
}La propiedad birthday se basa en la propiedad date y hereda su estructura. Tiene un nombre diferente ya que esta ideada específicamente para realizar un seguimiento de la fecha de cumpleaños del perfil. El uso de esta propiedad facilita la segmentación de clientes por edad o día del mes cuando se utilizan Segmentos o Trayectos.
{
"id": "MQNKalb7",
"kind": "birthday",
"name": null,
"value": {
"day": 3,
"month": 11,
"year": 1985
}
}{
"id": "MQNKalb7",
"kind": "checkbox",
"name": null,
"value": false
}{
"id": "MQNKalb7",
"kind": "company",
"name": null,
"value": "ACME Corporation"
}{
"id": "MQNKalb7",
"kind": "date",
"name": null,
"value": {
"day": 3,
"month": 11,
"year": 1985
}
}{
"id": "MQNKalb7",
"kind": "email",
"name": null,
"value": "will.e@acme.com",
"verified": true
}{
"id": "MQNKalb7",
"kind": "gender",
"name": null,
"value": "male"
}{
"id": "MQNKalb7",
"kind": "mercadolibre",
"name": null,
"value": "WILLE900001"
}{
"id": "MQNKalb7",
"kind": "number",
"name": null,
"value": 29.99
}{
"id": "MQNKalb7",
"kind": "phone",
"name": null,
"value": "+59898000001",
"verified": true
}{
"id": "MQNKalb7",
"kind": "tags",
"name": null,
"value": [
"tag1",
"tag2"
]
}{
"id": "MQNKalb7",
"kind": "text",
"name": null,
"value": "Long lasting customer"
}{
"id": "MQNKalb7",
"kind": "url",
"name": null,
"value": "https://www.hellotext.com"
}Crear una propiedad
Crea una nueva propiedad.
address
email
phone
checkbox
date
number
tags
text
url
- - El nombre no puede estar duplicado.
- - El nombre no puede comenzar con un número. Por ejemplo,
1er-nombrees inválido. - - El nombre no puede contener llaves. Por ejemplo,
{nombre}es inválido.
address, email o phone. Requerido al crear propiedades de tipo address, email o phone.
false. La singularidad de la propiedad determina si varios perfiles pueden tener el mismo valor.
Las propiedades únicas aseguran que no haya dos perfiles con el mismo valor. Esto es útil en casos en los que deseas que un solo perfil tenga un valor específico en un momento determinado.
curl -X POST https://api.hellotext.com/v1/properties
-d profile="OBYBnY69"
-d kind="text"
-d name="My Property"
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "OBYBnY69",
"type": "property",
"created_at": 1665684173,
"kind": "text",
"name": "My Property",
"position": 8,
"profile": "OBYBnY69",
"unique": false
}Obtener una propiedad
Obtener una propiedad existente.
curl -G https://api.hellotext.com/v1/properties/OBYBnY69
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."Modificar una propiedad
Modifica la propiedad especificada con la información proporcionada.
- - El nombre no puede estar duplicado.
- - El nombre no puede comenzar con un número. Por ejemplo,
1er-nombrees inválido. - - El nombre no puede contener llaves. Por ejemplo,
{nombre}es inválido.
position='' mueve la propiedad al final de la lista de propiedades.
curl -X PATCH https://api.hellotext.com/v1/properties/:id
-d name="My Renamed Property"
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "OBYBnY69",
"type": "property",
"created_at": 1665684173,
"kind": "text",
"name": "My Renamed Property",
"position": 8,
"profile": null,
"unique": false
}Eliminar una propiedad
Elimina permanentemente la propiedad especificada.
curl -X DELETE https://api.hellotext.com/v1/properties/OBYBnY69
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "OBYBnY69",
"type": "property",
"deleted": true
}Listar todas las propiedades
Enumera las propiedades existentes ordenadas por las más recientes. Los parámetros de paginación están disponibles en listas.
curl -G https://api.hellotext.com/v1/properties
-d limit=5
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"properties": [
{
"id": "OBYBnY69",
"type": "property",
"created_at": 1665684173,
"kind": "text",
"name": "My Property",
"position": 8,
"profile": null,
"unique": false
},
"{...}",
"{...}"
]
}Listas
Las listas actúan como agrupación lógica de perfiles.
-
POST
v1/lists
-
GET
v1/lists/:id
-
PATCH
v1/lists/:id
-
DELETE
v1/lists/:id
-
GET
v1/lists
El objecto de la lista
{
"id": "zN4Xx4Km",
"type": "list",
"name": "Greens",
"created_at": 1665684173
}Crear una lista
Crea una nueva lista
curl -X POST https://api.hellotext.com/v1/lists
-d name="Beauty & Care"
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "zN4Xx4Km",
"type": "list",
"name": "Beauty & Care",
"created_at": 1665684173
}Obtener una lista
Recupera una lista existente. Puedes especificar la lista a través de sus atributos id o name.
curl -G https://api.hellotext.com/v1/lists/zN4Xx4Km
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."Modificar una lista
Actualiza una lista existente. Puedes actualizar una lista a través de sus atributos id o name.
curl -X PATCH https://api.hellotext.com/v1/lists/zN4Xx4Km
-d name="Loyal customers"
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "zN4Xx4Km",
"type": "list",
"name": "Loyal customers",
"created_at": 1665684173
}Eliminar una lista
Elimina una lista existente. Puedes eliminar una lista a través de sus atributos id o name.
curl -X DELETE https://api.hellotext.com/v1/lists/zN4Xx4Km
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "zN4Xx4Km",
"type": "list",
"deleted": true
}Listar todas las listas
Enumera las listas existentes ordenados por los más recientes. Los parámetros de paginación están disponibles en listas.
curl -G https://api.hellotext.com/v1/lists
-d limit=5
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"lists": [
{
"id": "zN4Xx4Km",
"type": "list",
"name": "Greens",
"created_at": 1665684173
},
"{...}",
"{...}"
]
}Agregar perfil a la lista
Agrega un perfil a una lista si el perfil no está ya en la lista. Puedes especificar la lista a través de sus atributos id o name.
curl -X POST https://api.hellotext.com/v1/lists/dWJ8VYmz/profiles/MzYwlE50 \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"id": "MzYwlE50",
"type": "profile",
"blocked": false,
"created_at": 1665684173,
"emails": [
"will.e@acme.com"
],
"first_name": "Will E",
"last_name": "Coyote",
"lists": [
{
"id": "zN4Xx4Km",
"type": "list",
"name": "Greens",
"created_at": 1665684173
}
],
"phones": [
"+59898000001"
],
"properties": [
{
"id": "MQNKalb7",
"kind": "address",
"value": {
"city": "Montevideo",
"country": "UY",
"latitude": "-0.349044168e2",
"longitude": "-0.561370421e2",
"notes": null,
"postal_code": "11300",
"region": "Departamento de Montevideo",
"street": {
"name": "Av. Luis Alberto de Herrera",
"number": "1248"
},
"subregion": "CH"
}
},
{
"id": "MQNKalb7",
"kind": "birthday",
"name": null,
"value": {
"day": 3,
"month": 11,
"year": 1985
}
},
{
"id": "MQNKalb7",
"kind": "email",
"name": null,
"value": "will.e@acme.com",
"verified": true
},
{
"id": "MQNKalb7",
"kind": "phone",
"name": null,
"value": "+59898000001",
"verified": true
},
{
"id": "MQNKalb7",
"kind": "gender",
"name": null,
"value": "male"
}
],
"state": "subscribed",
"verified_emails": [
"will.e@acme.com"
],
"verified_phones": [
"+59898000001"
]
}Eliminar perfil de la lista
Elimina un perfil de una lista si el perfil es miembro de la lista. Puedes especificar la lista a través de sus atributos id o name.
curl -X DELETE https://api.hellotext.com/v1/lists/dWJ8VYmz/profiles/MzYwlE50 \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"id": "MzYwlE50",
"type": "profile",
"blocked": false,
"created_at": 1665684173,
"emails": [
"will.e@acme.com"
],
"first_name": "Will E",
"last_name": "Coyote",
"lists": [
],
"phones": [
"+59898000001"
],
"properties": [
{
"id": "MQNKalb7",
"kind": "address",
"value": {
"city": "Montevideo",
"country": "UY",
"latitude": "-0.349044168e2",
"longitude": "-0.561370421e2",
"notes": null,
"postal_code": "11300",
"region": "Departamento de Montevideo",
"street": {
"name": "Av. Luis Alberto de Herrera",
"number": "1248"
},
"subregion": "CH"
}
},
{
"id": "MQNKalb7",
"kind": "birthday",
"name": null,
"value": {
"day": 3,
"month": 11,
"year": 1985
}
},
{
"id": "MQNKalb7",
"kind": "email",
"name": null,
"value": "will.e@acme.com",
"verified": true
},
{
"id": "MQNKalb7",
"kind": "phone",
"name": null,
"value": "+59898000001",
"verified": true
},
{
"id": "MQNKalb7",
"kind": "gender",
"name": null,
"value": "male"
}
],
"state": "subscribed",
"verified_emails": [
"will.e@acme.com"
],
"verified_phones": [
"+59898000001"
]
}El objeto de plantilla
El objeto de plantilla representa un mensaje reutilizable que se puede reutilizar rápidamente en la Composición.
Con las plantillas, creas tu mensaje una vez y lo reutilizas tantas veces como quieras. No necesitas reescribir el mismo mensaje múltiples veces.
Puedes crear una plantilla para un mensaje que envías con frecuencia, como un boletín semanal, un informe mensual o un recordatorio.
Las plantillas están compuestas por componentes, que representan diferentes partes del mensaje. Algunas tecnologías admiten componentes de plantilla como WhatsApp, otras como SMS no lo hacen. Si una plantilla se envía por SMS, incluso si contiene otros componentes, solo se utiliza el componente body.
Las plantillas están compuestas por cuatro componentes principales que defines al crear una plantilla: header, body, footer, y buttons. Los componentes que eliges para cada una de tus plantillas deben basarse en las necesidades de tu negocio. El único componente requerido es el componente del cuerpo.
El componente opcional header admite tres tipos, address, attachment y text. Los encabezados de las direcciones se muestran como una vista previa del mapa que abre la aplicación de mapas predeterminada del cliente en su dispositivo. Los encabezados de los archivos adjuntos se muestran como una vista previa del archivo adjunto. Los encabezados de texto se muestran en WhatsApp como encabezado encima del mensaje y están limitados a 60 caracteres.
El componente requerido body es el contenido real del mensaje. Esta es la parte principal del mensaje que deseas enviar. Admite parámetros, que son marcadores de posición que puedes usar para personalizar el mensaje para cada destinatario.
El componente opcional footer se muestra en la parte inferior del mensaje. Se puede usar para proporcionar información adicional o un llamado a la acción. Recomendamos usar el componente pie de página para proporcionar una forma para que el destinatario opte por no recibir mensajes. Como “Envía STOP para cancelar la suscripción”. El pie de página está limitado a 160 caracteres.
El componente opcional buttons se muestra en la parte inferior del mensaje. Se puede usar para proporcionar una forma para que el destinatario interactúe con el mensaje. Las plantillas admiten hasta 10 botones en total. Cada tipo también tiene un cierto límite; lee más abajo para obtener más información.
-
POST
v1/templates
-
GET
v1/templates/:id
-
PATCH
v1/templates/:id
-
DELETE
v1/templates/:id
-
GET
v1/templates
El objeto de plantilla
position que especificaste al crear o actualizar la plantilla.
approved
La plantilla está aprobada y se puede usar para enviar mensajes. Las plantillas dirigidas a sms o any (cuando el negocio no ha integrado una cuenta de WhatsApp) se configuran automáticamente en estado approved.
pending
La plantilla está pendiente de aprobación. Las plantillas dirigidas a whatsapp o any (cuando el negocio ha integrado una cuenta de WhatsApp) se configuran automáticamente en estado pending. Una vez que la plantilla de WhatsApp es aprobada, se establece en estado approved.
rejected
La plantilla ha sido rechazada y no se puede usar para enviar mensajes. Actualiza la plantilla para volver a enviarla para aprobación.
any
Defecto
Un alias para todas las plataformas conectadas en el momento de la creación de la plantilla, como SMS, WhatsApp, Instagram, etc. Si en el momento de la creación de la plantilla el negocio no ha integrado WhatsApp, y lo integra en una fecha posterior, se crea automáticamente una plantilla de WhatsApp.
sms
Esta plantilla está destinada a mensajes SMS. La plantilla no se puede usar en WhatsApp.
whatsapp
Esta plantilla está destinada a mensajes de WhatsApp. La plantilla no se puede usar en SMS.
{
"id": "MzYwlE50",
"type": "template",
"body": "Hello, how can I help you today?",
"buttons": [
{
"type": "copy",
"copy": "123456",
"text": "Copy text"
},
{
"type": "url",
"text": "Visit our website",
"url": "https://example.com"
},
{
"type": "phone",
"phone": "+1234567890",
"text": "Call us"
},
{
"type": "quick_reply",
"text": "Button text"
},
{
"type": "quick_reply",
"text": "Button text"
},
{
"type": "quick_reply",
"text": "Button text"
}
],
"created_at": 1665684173,
"footer": "Send STOP to unsubscribe",
"state": "approved",
"header": {
"type": "text",
"text": "Welcome to our store"
}
}Tipos de Encabezado
El componente de encabezado es opcional y admite tres tipos, address, attachment y text. Los encabezados de texto se muestran en WhatsApp como un encabezado sobre el mensaje y están limitados a 60 caracteres. Los encabezados adjuntos se muestran como una vista previa del archivo adjunto.
El tipo de encabezado address se utiliza para mostrar un mapa en el que se puede hacer clic y que abre la aplicación de mapas predeterminada del cliente. Esto es útil para proporcionar al destinatario una ubicación o indicaciones para llegar a una ubicación, como una tienda u oficina.
El tipo de encabezado text se utiliza para mostrar un encabezado de texto sobre el mensaje. El encabezado de texto está limitado a 60 caracteres.
El tipo de encabezado attachment se utiliza para mostrar una vista previa de un archivo adjunto. El archivo adjunto se descarga y se almacena en los servidores de Hellotext. La vista previa del archivo adjunto no se muestra en los mensajes SMS.
Notas sobre adjuntos
- Cada plataforma tiene diferentes limitaciones en el tamaño y tipo de adjuntos que se pueden enviar. A continuación se muestra una lista de los tipos de archivo compatibles y el tamaño máximo de archivo para cada plataforma.
- Si bien Hellotext convierte automáticamente el archivo adjunto a un formato compatible con la plataforma, es mejor que el archivo adjunto esté en los formatos admitidos para evitar la pérdida de datos durante la conversión. Asegúrese de que el tamaño del archivo esté dentro de las limitaciones de la plataforma resaltadas a continuación.
| Tipo de Medio | Formatos Compatibles | Tamaño Máximo |
Imagen |
jpeg, png |
5MB |
Video |
3gp, mp4 |
25MB |
Documento |
pdf, doc, docx, ppt, pptx, xls, xlsx |
100MB |
| Tipo de Medio | Formatos Compatibles | Tamaño Máximo |
Imagen |
png, jpeg, gif |
8MB |
Video |
mp4, ogg, avi, mov, webm |
25MB |
{
"type": "address",
"address": {
"city": "Montevideo",
"country": "UY",
"latitude": "-0.349044168e2",
"longitude": "-0.561370421e2",
"notes": null,
"postal_code": "11300",
"region": "Departamento de Montevideo",
"street": {
"name": "Av. Luis Alberto de Herrera",
"number": "1248"
},
"subregion": "CH"
}
}{
"type": "text",
"text": "Welcome to our store"
}{
"type": "attachment",
"attachment_url": "https://www.hellotext.com/my-amazing-image.jpg"
}Cuerpo de la Plantilla
El componente cuerpo es el único componente requerido de una plantilla. Esta es la parte principal del mensaje que deseas enviar. Admite parámetros, que son marcadores de posición que puedes usar para personalizar el mensaje para cada destinatario.
Los parámetros son etiquetas dinámicas que puedes usar para personalizar el mensaje para cada destinatario. Cuando envías un mensaje de plantilla, puedes reemplazar los parámetros con los valores reales.
Hay dos categorías de parámetros que puedes usar en una plantilla, estas son tags y shortlinks.
Los parámetros están incrustados en el cuerpo de la plantilla, están encerrados dentro de llaves angulares {}. Cuando envías un mensaje de plantilla, puedes reemplazar los parámetros con los valores reales.
Las etiquetas propiedades se utilizan para personalizar el mensaje con la información del destinatario. Por ejemplo, puedes usar el nombre, dirección de correo electrónico o número telefónico del destinatario. Además, puedes usar cualquier propiedad personalizada que hayas definido.
Consulta las Propiedades para obtener más información sobre cómo crear una propiedad. También puedes crear propiedades en el panel.
Aprende más sobre etiquetas y cómo funcionan, así como las reglas aplicadas a ellas.
Propiedades
{name}
Dirige al primer nombre del perfil.
{full_name}
Dirige al nombre completo del perfil.
{last_name}
Dirige al apellido del perfil.
{birthday}
Dirige al cumpleaños del perfil.
{email}
Dirige al correo electrónico predeterminado del perfil.
{phone}
Dirige al número telefónico predeterminado del perfil.
{address}
Dirige a la dirección predeterminada del perfil.
{company}
Dirige a la propiedad empresarial del perfil.
Además de las etiquetas anteriores, puedes dirigir cualquier propiedad personalizada que hayas definido.
Las reglas son simples; escribes el nombre de la propiedad dentro de llaves angulares < code>{}. Aunque no distingue mayúsculas y minúsculas, se recomienda utilizar las mismas mayúsculas que el nombre de la propiedad.
{
"id": "MzYwlE50",
"type": "template",
"body": "Hello {name}, thank you for contacting us. Our team will get back to you shortly."
}{
"id": "MzYwlE50",
"type": "template",
"body": "Hello {name}, since {birthday} is your birthday, we have a special gift for you. Click the link to claim it."
}{
"id": "MzYwlE50",
"type": "template",
"body": "Hello {name}, we have sent further details to {email}."
}{
"id": "MzYwlE50",
"type": "template",
"body": "Hello {name}, with passport number {passport}, your ticket is confirmed. Have a safe trip."
}ShortLinks es un servicio acortador de enlaces operado por Hellotext que te permite acortar URLs y redirigirlas a una URL específica.
Las redirecciones ShortLink adjuntan un identificador hello_session a la URL, luego puedes aprovechar Hellotext.js para rastrear eventos e interacciones del usuario con ShortLink hacia Hellotext. Estos eventos aparecen en la Actividad Trail de ese perfil.
Usar ShortLinks en plantillas es sencillo; las mismas reglas aplican como con las etiquetas propiedades. Hay dos categorías de ShortLinks, dinámicos y estáticos.
ShortLinks Estáticos
Los ShortLinks estáticos son enlaces cortos que son los mismos para todos los destinatarios. Esto es útil si deseas rastrear cuántos clics hay en una URL específica.
El formato es {shortlink:url}, donde url es la URL que deseas acortar. Por ejemplo, {shortlink:https://hellotext.com} genera un ShortLink que redirige a https://hellotext.com, adjuntando un identificador hello_session.
ShortLinks Dinámicos
Los ShortLinks dinámicos son enlaces cortos personalizados para cada destinatario. Esto es útil si cada mensaje que envías a un cliente tiene una URL única específica para ese cliente.
El formato es {shortlink:name}, donde name es el nombre variable que deseas utilizar.
Por ejemplo, si deseas enviar un mensaje a un cliente con una URL única a su página cuenta, puedes usar {shortlink:cantidad} como ShortLink. Cuando envías el mensaje, reemplazas el ShortLink con la URL real.
{
"id": "MzYwlE50",
"type": "template",
"body": "Hello {name}, celebrate the holidays season with our special limited time offers. Click {shortlink:https://shop.com/holidays} to view the collection."
}{
"id": "MzYwlE50",
"type": "template",
"body": "Hello {name}, this is a remainder that your appointment is scheduled for {date}. Click {shortlink:appointment} to view the details, or you can reschedule by clicking {shortlink:reschedule}."
}Tipos de Botones
Los botones son componentes interactivos opcionales que realizan acciones específicas cuando se tocan. Las plantillas pueden tener una mezcla total de hasta 10 componentes botón, aunque hay límites para botones individuales del mismo tipo así como límites combinados. Estos límites están descritos abajo.
Los botones pueden incluir un argumento posición entre 0 y 9 para indicar el orden del botón; se selecciona automáticamente una posición basada en el índice del botón al crear o actualizar botones plantillas.
Botones URL
Los botones URL cargan la URL especificada en el navegador web predeterminado del dispositivo cuando son tocados por el usuario de la aplicación.
Las plantillas están limitadas a 2 botones URL.
{
"type": "url",
"text": "Visit our website",
"url": "https://example.com"
}Botones Teléfono
Los botones número telefónico llaman al número telefónico comercial especificado cuando son tocados por el usuario de la aplicación.
Las plantillas están limitadas a uno botón número telefónico.
{
"type": "phone",
"phone": "+1234567890",
"text": "Call us"
}Botones Respuesta Rápida
Los botones respuesta rápida son botones personalizados solo texto que te envían inmediatamente un mensaje con la cadena especificada cuando son tocados por el usuario de la aplicación. Un caso común es un botón que permite a tu cliente optar fácilmente por no recibir mensajes publicitarios.
Las plantillas están limitadas a diez botones respuesta rápida.
{
"type": "quick_reply",
"text": "Button text"
}Botones Copiar
Los botones copiar código copian una cadena textual (definida cuando se envía la plantilla en un mensaje) al portapapeles del dispositivo cuando son tocados por el usuario de la aplicación.
Las plantillas están limitadas a uno botón copiar código.
{
"type": "copy",
"copy": "123456",
"text": "Copy text"
}Crear una Plantilla
Crea un nuevo objeto de plantilla.
Notas
- Las plantillas de WhatsApp están limitadas a 1024 caracteres. Las plantillas de WhatsApp solo se pueden crear cuando la empresa tiene una cuenta de WhatsApp Business integrada que no ha sido deshabilitada, restringida o prohibida.
- Las plantillas de SMS están limitadas a 160 caracteres.
-
La plantilla de SMS no admite los componentes
header,footerobuttons. Al intentar asignar estos componentes se devuelve un errorinvalid.
Se selecciona una posición automática en función del índice del botón cuando no se especifica ninguna
position. Puede incluir un argumento opcional position entre 1 y 10 para indicar el orden del botón.
any - es un alias para todas las plataformas conectadas, SMS, WhatsApp, Instagram, etc. Cuando la empresa ha integrado una cuenta de WhatsApp, any creará la plantilla para dirigirse tanto a WhatsApp como a SMS. sms - Esta plantilla está destinada a mensajes SMS. La plantilla no se puede usar en WhatsApp. whatsapp - Esta plantilla está destinada a mensajes de WhatsApp. La plantilla no se puede usar en SMS. Las plantillas que tienen como objetivo WhatsApp se configuran automáticamente en estado pending. Una vez que la plantilla de WhatsApp es aprobada, se establece en estado approved.
any
Defecto
sms
whatsapp
curl -X POST https://api.hellotext.com/v1/templates
-d body="Hello {name}, how can we assist you today?"
-d footer="One of our agents will be with you shortly."
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "MzYwlE50",
"type": "template",
"body": "Hello, how can I help you today?",
"buttons": [
{
"type": "copy",
"copy": "123456",
"text": "Copy text"
},
{
"type": "url",
"text": "Visit our website",
"url": "https://example.com"
},
{
"type": "phone",
"phone": "+1234567890",
"text": "Call us"
},
{
"type": "quick_reply",
"text": "Button text"
},
{
"type": "quick_reply",
"text": "Button text"
},
{
"type": "quick_reply",
"text": "Button text"
}
],
"created_at": 1665684173,
"footer": "Send STOP to unsubscribe",
"state": "approved",
"header": {
"type": "text",
"text": "Welcome to our store"
}
}Recuperar una Plantilla
Recupera un objeto de plantilla.
curl -G https://api.hellotext.com/v1/templates/xJEOaPdk
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "xJEOaPdk",
"type": "template",
"body": "Hello, how can I help you today?",
"buttons": [
{
"type": "copy",
"copy": "123456",
"text": "Copy text"
},
{
"type": "url",
"text": "Visit our website",
"url": "https://example.com"
},
{
"type": "phone",
"phone": "+1234567890",
"text": "Call us"
},
{
"type": "quick_reply",
"text": "Button text"
},
{
"type": "quick_reply",
"text": "Button text"
},
{
"type": "quick_reply",
"text": "Button text"
}
],
"created_at": 1665684173,
"footer": "Send STOP to unsubscribe",
"state": "approved",
"header": {
"type": "text",
"text": "Welcome to our store"
}
}Actualizar una Plantilla
Actualiza un objeto de plantilla.
Notas sobre las Plantillas de WhatsApp
-
Las plantillas dirigidas a WhatsApp están limitadas a 1 actualización por día. Esto significa que si actualizas una plantilla de WhatsApp, no podrás actualizarla de nuevo hasta que hayan pasado 24 horas. Intentar actualizar una plantilla de WhatsApp más de una vez en un día será rechazado con un error
invalid. -
Además, una plantilla de WhatsApp solo se puede editar cuando está aprobada, rechazada o pausada. Intentar actualizar una plantilla de WhatsApp que esté en estado
pendingserá rechazado con un errorinvalid. -
Los nombres no se pueden cambiar. Si proporciona
nameen los parámetros, se ignora.
[] para eliminar todos los botones de la plantilla.
null o {} para eliminar el encabezado. Si el tipo de encabezado era un adjunto, el adjunto se elimina de los servidores de Hellotext.
whatsapp a sms hará que la plantilla sea inutilizable en WhatsApp, lo que significa que no podrás enviar mensajes usando esta plantilla en WhatsApp. WhatsApp solo puede configurarse cuando la empresa ha integrado una cuenta de WhatsApp. Si intentas crear una plantilla de WhatsApp pero no has integrado WhatsApp, se devolverá un error.
any
Defecto
sms
whatsapp
curl -X PATCH https://api.hellotext.com/v1/templates/xJEOaPdk
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "xJEOaPdk",
"type": "template",
"body": "Hello, how can I help you today?",
"buttons": [
{
"type": "copy",
"copy": "123456",
"text": "Copy text"
},
{
"type": "url",
"text": "Visit our website",
"url": "https://example.com"
},
{
"type": "phone",
"phone": "+1234567890",
"text": "Call us"
},
{
"type": "quick_reply",
"text": "Button text"
},
{
"type": "quick_reply",
"text": "Button text"
},
{
"type": "quick_reply",
"text": "Button text"
}
],
"created_at": 1665684173,
"footer": "Send STOP to unsubscribe",
"state": "approved",
"header": {
"type": "text",
"text": "Welcome to our store"
}
}Eliminar una Plantilla
Elimina un objeto de plantilla.
El objeto de plantilla se mantiene para referencia interna, ya que puede haber habido mensajes que dependían de él antes de la eliminación. Sin embargo, la plantilla se vuelve inaccesible y no se puede usar para enviar nuevos mensajes. Puedes crear una nueva plantilla con el mismo nombre.
Notas sobre las Plantillas de WhatsApp
- Los nombres de una plantilla aprobada que se ha eliminado no se pueden volver a utilizar durante 30 días.
- Solo puedes crear una nueva plantilla con el mismo nombre cuando la plantilla eliminada no estaba dirigida a WhatsApp.
curl -X DELETE https://api.hellotext.com/v1/templates/xJEOaPdk
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "MzYwlE50",
"type": "template",
"deleted": true
}Listar todas las Plantillas
Lista todos los objetos de plantilla. Soporta paginación.
curl -G https://api.hellotext.com/v1/templates
-d limit=5
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"templates": [
{
"id": "MzYwlE50",
"type": "template",
"body": "Hello, how can I help you today?",
"buttons": [
{
"type": "copy",
"copy": "123456",
"text": "Copy text"
},
{
"type": "url",
"text": "Visit our website",
"url": "https://example.com"
},
{
"type": "phone",
"phone": "+1234567890",
"text": "Call us"
},
{
"type": "quick_reply",
"text": "Button text"
},
{
"type": "quick_reply",
"text": "Button text"
},
{
"type": "quick_reply",
"text": "Button text"
}
],
"created_at": 1665684173,
"footer": "Send STOP to unsubscribe",
"state": "approved",
"header": {
"type": "text",
"text": "Welcome to our store"
}
},
"{...}",
"{...}"
]
}El Objeto de Mensaje
Un mensaje es una comunicación entre usted y un perfil. Puede enviar mensajes de texto o reutilizar una Plantilla existente.
-
POST
v1/messages
-
GET
v1/messages/:id
-
GET
v1/messages
El Objeto de Mensaje
delivered
El mensaje ha sido entregado exitosamente. Consulte delivered_at para la hora exacta.
failed
El mensaje no se pudo entregar.
pending
Defecto
El mensaje se ha creado correctamente y está pendiente de entrega.
received
El mensaje fue enviado por el perfil a la empresa.
routed
El mensaje ha sido dirigido a la pasarela externa. Una vez que el proveedor informe, el mensaje será delivered o failed.
instagram
El mensaje se entregó por Instagram.
mercadolibre
El mensaje se entregó por MercadoLibre.
sms
El mensaje se entregó por SMS.
whatsapp
El mensaje se entregó por WhatsApp.
{
"id": "zGrDJ1Lb",
"type": "message",
"attachments": [
],
"body": "Hi John, how can we help you today?",
"created_at": 1665684173,
"delivered_at": 1665684173,
"destination": "+1234567890",
"failed_at": null,
"origin": "+0987654321",
"profile": "APwbZ6w4",
"routed_at": 1665684173,
"state": "delivered",
"technology": "whatsapp",
"template": "MzYwlE50"
}Mensajes de Plantilla
Aprenda cómo enviar mensajes usando una plantilla. Asegúrese de haber leído sobre las Plantillas y de entender los componentes y cómo usarlos antes de enviar un mensaje.
Enlaces Cortos Dinámicos en Mensajes de Plantilla
Puede reservar un espacio para enlaces cortos dinámicos en el cuerpo de la plantilla cuando la crea. Consulte la documentación de Tipos de Enlaces Cortos para obtener más información sobre los tipos de enlaces cortos y cómo crearlos.
Las siguientes secciones asumen que ya ha creado una plantilla con enlaces cortos dinámicos y tiene un conocimiento sólido sobre cómo funcionan.
Cada enlace corto dinámico es un nombre de variable que se puede dirigir y reemplazar con una URL específica al enviar el mensaje. Considere que la plantilla que queremos usar tiene tres etiquetas. Una etiqueta de propiedad {name} que se reemplaza por el nombre de pila del perfil. Y dos enlaces cortos dinámicos, {shortlink:appointment} y {shortlink:reschedule}.
Para reemplazar los enlaces cortos al enviar el mensaje, proporcione el nombre de cada enlace corto dinámico con una URL a través de un parámetro shortlinks en el objeto de la plantilla.
Si observa los Parámetros del Mensaje que tenemos al crear el mensaje, verá que en message.template.shortlinks tenemos un hash con los nombres de los enlaces cortos y sus respectivas URL. Cada URL proporcionada se acorta y reemplaza el enlace corto dinámico en el cuerpo de la plantilla, el orden no importa ya que las secciones dinámicas se reemplazan por sus nombres respectivos.
{
"id": "MzYwlE50",
"type": "template",
"body": "Hello {name}, this is a remainder that your appointment is scheduled for {date}. Click {shortlink:appointment} to view the details, or you can reschedule by clicking {shortlink:reschedule}."
}{
"profile": "APwbZ6w4",
"origin": "+0987654321",
"template": {
"id": "MzYwlE50",
"shortlinks": {
"appointment": "https://example.com/appointments/1",
"reschedule": "https://example.com/appointments/1/edit"
}
}
}Enviar un Mensaje
Envía un mensaje de texto libre o un mensaje de plantilla para enviar a un perfil.
Notas
- Los mensajes de WhatsApp están limitados a 4096 caracteres. Los mensajes de WhatsApp solo se pueden enviar cuando la empresa tiene una cuenta de WhatsApp Business integrada que no ha sido deshabilitada, restringida o prohibida.
- Los mensajes de Instagram están limitados a 1000 caracteres. Los mensajes de Instagram solo se pueden enviar cuando la empresa tiene un perfil de Instagram integrado.
- Los mensajes de MercadoLibre están limitados a 350 caracteres. Los mensajes de MercadoLibre solo se pueden enviar cuando la empresa tiene una tienda de MercadoLibre integrada.
- Los mensajes de SMS están limitados a 160 caracteres.
-
Como recordatorio, asegúrate de enviar mensajes solo a usuarios que no hayan optado por dejar de recibir mensajes de ti. Consulta el
subscription_statedel perfil para obtener más información. - Cuando se usa una plantilla que utiliza Enlaces Cortos Dinámicos, es necesario proporcionar las URL de los enlaces cortos al crear el mensaje. No proporcionar una URL para un enlace corto dinámico resultará en errores.
Notas sobre Mensajes de WhatsApp
- Solo puedes enviar un mensaje de texto libre a un perfil si el perfil tiene una ventana de conversación abierta. De lo contrario, debes usar una plantilla. Esto se llama Ventana de Atención al Cliente.
- Cada vez que un perfil te envía un mensaje a través de WhatsApp, se inicia un temporizador de 24 horas llamado ventana de atención al cliente (o se refresca si ya se ha iniciado uno).
- Cuando hay una ventana de atención al cliente abierta entre tú y un usuario, puedes enviar mensajes de texto libre al usuario. Si no hay una ventana abierta entre tú y el usuario, solo puedes enviar mensajes de plantilla al usuario, ya que los mensajes de plantilla son el único tipo que se puede enviar fuera de una ventana de atención al cliente.
Notas sobre adjuntos
- Cada plataforma tiene diferentes limitaciones en el tamaño y tipo de adjuntos que se pueden enviar. A continuación se muestra una lista de los tipos de archivo compatibles y el tamaño máximo de archivo para cada plataforma.
- Si bien Hellotext convierte automáticamente el archivo adjunto a un formato compatible con la plataforma, es mejor que el archivo adjunto esté en los formatos admitidos para evitar la pérdida de datos durante la conversión. Asegúrese de que el tamaño del archivo esté dentro de las limitaciones de la plataforma resaltadas a continuación.
| Tipo de Medio | Formatos Compatibles | Tamaño Máximo |
Imagen |
jpeg, png |
5MB |
Video |
3gp, mp4 |
25MB |
Documento |
pdf, doc, docx, ppt, pptx, xls, xlsx |
100MB |
| Tipo de Medio | Formatos Compatibles | Tamaño Máximo |
Imagen |
png, jpeg, gif |
8MB |
Video |
mp4, ogg, avi, mov, webm |
25MB |
Hellotext selecciona automáticamente un destino basado en el
origin y technology configurados. De lo contrario, puede especificar el destino para enviar el mensaje a un identificador específico del perfil.
Por ejemplo, al enviar un mensaje a un perfil, si no especifica el
origin, Hellotext usará un canal con el que se pueda contactar al perfil. Esto significa que, si el perfil se puede contactar a través de WhatsApp, el mensaje se envía a través de WhatsApp, y si el perfil se puede contactar a través de SMS, el mensaje se envía a través de SMS.
Tenga en cuenta que integraciones como WhatsApp, Instagram o MercadoLibre requieren una integración activa conectada por el negocio. Intentar enviar un mensaje a través de una tecnología no disponible devolverá un error
invalid.
instagram
sms
whatsapp
curl -X POST https://api.hellotext.com/v1/messages
-d origin="+14155552671"
-d profile="zGrDJ1Lb"
-d template="K75Vq1dL"
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "zGrDJ1Lb",
"type": "message",
"attachments": [
],
"body": "Hi John, how can we help you today?",
"created_at": 1665684173,
"delivered_at": null,
"destination": "+14155552672",
"failed_at": null,
"origin": "+14155552671",
"profile": "zGrDJ1Lb",
"routed_at": null,
"state": "pending",
"technology": "whatsapp",
"template": "K75Vq1dL"
}curl -X POST https://api.hellotext.com/v1/messages
-d origin="+14155552671"
-d profile="zGrDJ1Lb"
-d body="To be or not to be, that is the question."
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "zGrDJ1Lb",
"type": "message",
"attachments": [
],
"body": "To be or not to be, that is the question.",
"created_at": 1665684173,
"delivered_at": null,
"destination": "+14155552672",
"failed_at": null,
"origin": "+14155552671",
"profile": "zGrDJ1Lb",
"routed_at": null,
"state": "pending",
"technology": "whatsapp",
"template": null
}Mostrar un Mensaje
Muestra un mensaje específico enviado por la empresa.
curl -G https://api.hellotext.com/v1/messages/APwbP54L
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."Listar Mensajes
Lista todos los mensajes enviados por la empresa.
curl -G https://api.hellotext.com/v1/messages
-d limit=5
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"messages": [
{
"id": "zGrDJ1Lb",
"type": "message",
"attachments": [
],
"body": "Hi John, how can we help you today?",
"created_at": 1665684173,
"delivered_at": 1665684173,
"destination": "+1234567890",
"failed_at": null,
"origin": "+0987654321",
"profile": "APwbZ6w4",
"routed_at": 1665684173,
"state": "delivered",
"technology": "whatsapp",
"template": "MzYwlE50"
},
"{...}",
"{...}"
]
}Cupones
Importa los cupones de tu eCommerce que te gustaría enviar en tus campañas promocionales. Puedes medir los resultados de los diferentes cupones.
-
POST
v1/coupons
-
GET
v1/coupons/:id
-
PATCH
v1/coupons/:id
-
DELETE
v1/coupons/:id
-
GET
v1/coupons
El objeto del cupón
{
"id": "xJEOaPdk",
"type": "coupon",
"code": "SALE",
"created_at": 1665684173,
"description": "Get 15% off all our summer sale",
"destination_url": "https://www.myshop.com/redeem/SALE",
"reference": null
}Crear un cupón
Crea un nuevo cupón.
SALE. Distingue mayúsculas y minúsculas. No se permiten códigos duplicados.
curl -X POST https://api.hellotext.com/v1/coupons
-d code="SALE"
-d description="Get 15% off all our summer sale"
-d destination_url="https://www.myshop.com/redeem/SALE"
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "xJEOaPdk",
"type": "coupon",
"code": "SALE",
"created_at": 1665684173,
"description": "Get 15% off all our summer sale",
"destination_url": "https://www.myshop.com/redeem/SALE",
"reference": null
}Obtener un cupón
Obtener un cupón existente.
curl -G https://api.hellotext.com/v1/coupons/xJEOaPdk
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."Modificar un cupón
Modifica el cupón especificado con la información proporcionada.
SALE. Distingue mayúsculas y minúsculas. No se permiten códigos duplicados.
curl -X PATCH https://api.hellotext.com/v1/coupons/xJEOaPdk
-d code="SALE15"
-d description="Get 15% off all our summer sale"
-d destination_url="https://www.myshop.com/redeem/SALE"
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "xJEOaPdk",
"type": "coupon",
"code": "SALE15",
"created_at": 1665684173,
"description": "Get 15% off all our summer sale",
"destination_url": "https://www.myshop.com/redeem/SALE",
"reference": null
}Eliminar un cupón
Elimina permanentemente el cupón especificado.
curl -X DELETE https://api.hellotext.com/v1/coupons/xJEOaPdk
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "xJEOaPdk",
"type": "coupon",
"deleted": true
}Listar todos los cupones
Enumera los cupones existentes ordenados por los más recientes. Los parámetros de paginación están disponibles en listas.
curl -G https://api.hellotext.com/v1/coupons
-d limit=5
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"coupons": [
{
"id": "xJEOaPdk",
"type": "coupon",
"code": "SALE",
"created_at": 1665684173,
"description": "Get 15% off all our summer sale",
"destination_url": "https://www.myshop.com/redeem/SALE",
"reference": null
},
"{...}",
"{...}"
]
}Seguimiento
El seguimiento de las interacciones de los clientes abre nuevas posibilidades de marketing y brinda a las empresas una vista completa del historial de cada cliente.
Mediante el seguimiento de las acciones de clientes, es posible crear audiencias segmentadas basadas en lo que hacen y les gusta, y usar esto para marketing de alta precisión. Las empresas pueden activar automatizaciones basadas en la actividad del cliente y dar a su equipo una gran ventaja encontrando nuevas oportunidades para interactuar activamente y vender más.
Una configuración mínima para realizar un seguimiento de un evento es establecer el parámetro action con cualquiera de las acciones pre-definidas o personalizadas (consulta Acciones) y el parámetro profile que representa el perfil del cliente o el session si el seguimiento de eventos se realiza a partir de enlaces cortos en campañas o rutas (ver Sesiones).
Al proporcionar los parámetros session y profile, asegúrese de que la sesión esté asignada al perfil. Las sesiones asignadas a un perfil no se pueden utilizar para realizar un seguimiento de los eventos de otro perfil. Si la sesión no está asignada a ningún perfil, se asignará automáticamente al perfil que pase al realizar el seguimiento de un evento.
Al proporcionar una currency. Se debe especificar el amount. Si no se proporciona ninguno, los valores se heredarán del trackable si el objeto tiene los atributos.
POST /v1/attribution/events
Eventos de app
Realiza un seguimiento de los eventos importantes realizados por tus clientes cuando interactúan con tu aplicación. Las acciones más comunes incluyen cuando una aplicación se instala con la acción app.installed, se elimina con app.removed o cuando un usuario gasta una determinada cantidad con app.spent.
Al rastrear eventos asociados a sesiones creadas después de una campaña, todos los valores de atribución, incluidos los valores monetarios, se agregarán a los informes de la campaña.
app.spent, app.installed y app.removed.
app.installed
app.removed
app.spent
null. Obligatorio si action=app.spent.
app. El app se va agregar y despues rastreado.
cantidad proporcionada en formato ISO 4217. El valor predeterminado siempre es USD. Obligatorio si action=app.spent.
session. Identificador único del objeto de perfil al que pertenece este evento. Si no se especifica explícitamente, el identificador de perfil se puede heredar cuando se especifica el parámetro session y la sesión ya está asociada a un perfil o se adjunta posteriormente a uno.
profile. Identificador del objeto de sesión al que pertenece este evento. Las sesiones son identificadores generados automáticamente a partir de los clics de los visitantes en enlaces cortos o de la librería Hellotext.js al realizar seguimientos de visitantes anónimos. Es una forma de rastrear eventos en el lado del cliente sin autenticar o revelar el identificador del perfil, lo que permite asociarlo más tarde a un perfil de forma segura en el lado del servidor. Más información sobre Sesiones.
created_at.
curl https://api.hellotext.com/v1/attribution/events \
-d action="app.installed" \
-d app=xnqJQ47v \
-d session=2KAGgAgm \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"status": "received"
}
Eventos de carrito
Realiza un seguimiento de los eventos realizados por los clientes cuando agregan o eliminan elementos de su carrito de compras. O abandonan el carrito
Los valores monetarios asociados a los elementos del carrito se agregarán a los informes de la campaña.
cart.abandoned
cart.added
cart.removed
null.
cantidad proporcionada en formato ISO 4217. El valor predeterminado siempre es USD.
id, reference o sku) y product_parameters y product_variant_parameters. Requerido cuando la acción es cart.added o cart.removed. Cuando no se proporciona un objeto Carrito, se creará automáticamente un objeto Carrito y los
productos se agregarán a él. Cuando se proporciona un objeto Carrito, los productos se agregarán al Carrito. Y los productos se mostrarán en la Trayectoria de Actividad del Perfil. Asegúrate de establecer la
reference o sku para el producto o la variante del producto para evitar la creación de productos duplicados.
session. Identificador único del objeto de perfil al que pertenece este evento. Si no se especifica explícitamente, el identificador de perfil se puede heredar cuando se especifica el parámetro session y la sesión ya está asociada a un perfil o se adjunta posteriormente a uno.
profile. Identificador del objeto de sesión al que pertenece este evento. Las sesiones son identificadores generados automáticamente a partir de los clics de los visitantes en enlaces cortos o de la librería Hellotext.js al realizar seguimientos de visitantes anónimos. Es una forma de rastrear eventos en el lado del cliente sin autenticar o revelar el identificador del perfil, lo que permite asociarlo más tarde a un perfil de forma segura en el lado del servidor. Más información sobre Sesiones.
created_at.
curl https://api.hellotext.com/v1/attribution/events \
-d action="cart.added" \
-d app=xnqJQ47v \
-d session=2KAGgAgm \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"status": "received"
}
Eventos de cupones
Realiza un seguimiento de los eventos realizados por tus clientes cuando canjean cupones. El valor disponible es coupon.redeemed para los cupones canjeados.
Los valores monetarios asociados al canje de cupones se agregarán a los informes de la campaña.
null.
coupon. El cupon se va agregar y despues rastreado.
cantidad proporcionada en formato ISO 4217. El valor predeterminado siempre es USD.
session. Identificador único del objeto de perfil al que pertenece este evento. Si no se especifica explícitamente, el identificador de perfil se puede heredar cuando se especifica el parámetro session y la sesión ya está asociada a un perfil o se adjunta posteriormente a uno.
profile. Identificador del objeto de sesión al que pertenece este evento. Las sesiones son identificadores generados automáticamente a partir de los clics de los visitantes en enlaces cortos o de la librería Hellotext.js al realizar seguimientos de visitantes anónimos. Es una forma de rastrear eventos en el lado del cliente sin autenticar o revelar el identificador del perfil, lo que permite asociarlo más tarde a un perfil de forma segura en el lado del servidor. Más información sobre Sesiones.
created_at.
curl https://api.hellotext.com/v1/attribution/events \
-d action="coupon.redeemed" \
-d coupon=wx4Vn4no \
-d session=2KAGgAgm \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"status": "received"
}
Eventos de formularios
Realiza un seguimiento de los eventos realizados por tus clientes cuando completan un formulario. Las acciones disponibles son form.completed.
Los valores monetarios asociados a la finalización del formulario se agregarán a los informes de la campaña.
null.
cantidad proporcionada en formato ISO 4217. El valor predeterminado siempre es USD.
form. El formulario se va agregar y despues rastreado.
session. Identificador único del objeto de perfil al que pertenece este evento. Si no se especifica explícitamente, el identificador de perfil se puede heredar cuando se especifica el parámetro session y la sesión ya está asociada a un perfil o se adjunta posteriormente a uno.
profile. Identificador del objeto de sesión al que pertenece este evento. Las sesiones son identificadores generados automáticamente a partir de los clics de los visitantes en enlaces cortos o de la librería Hellotext.js al realizar seguimientos de visitantes anónimos. Es una forma de rastrear eventos en el lado del cliente sin autenticar o revelar el identificador del perfil, lo que permite asociarlo más tarde a un perfil de forma segura en el lado del servidor. Más información sobre Sesiones.
created_at.
curl https://api.hellotext.com/v1/attribution/events \
-d action="form.completed" \
-d form=wx4Vn4no \
-d session=2KAGgAgm \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"status": "received"
}
Eventos de órdenes
Realiza un seguimiento de los eventos relacionados con el ciclo de vida de las ordenes de tus clientes. Las acciones disponibles son order.placed cuando un cliente realiza una orden, order.confirmed cuando se confirma, order.cancelled si se cancela y < code>order.shipped cuando se envía.
Los valores monetarios asociados a las órdenes se agregarán a los informes de la campaña.
order.cancelled
order.confirmed
order.delivered
order.placed
order.printed_label
order.shipped
null.
cantidad proporcionada en formato ISO 4217. El valor predeterminado siempre es USD.
order. El órden se va agregar y despues rastreado.
session. Identificador único del objeto de perfil al que pertenece este evento. Si no se especifica explícitamente, el identificador de perfil se puede heredar cuando se especifica el parámetro session y la sesión ya está asociada a un perfil o se adjunta posteriormente a uno.
profile. Identificador del objeto de sesión al que pertenece este evento. Las sesiones son identificadores generados automáticamente a partir de los clics de los visitantes en enlaces cortos o de la librería Hellotext.js al realizar seguimientos de visitantes anónimos. Es una forma de rastrear eventos en el lado del cliente sin autenticar o revelar el identificador del perfil, lo que permite asociarlo más tarde a un perfil de forma segura en el lado del servidor. Más información sobre Sesiones.
created_at.
curl https://api.hellotext.com/v1/attribution/events \
-d action="order.placed" \
-d order=wx4Vn4no \
-d session=2KAGgAgm \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"status": "received"
}
Eventos de productos
Seguimiento de los eventos de compras realizadas por tus clientes. Si tus clientes realizan órdenes, puedes realizar un seguimiento de las acciones de la orden. Las acciones de productos disponibles son product.purchased cuando un cliente compra un producto y product.viewed cuando un producto es visto.
Los valores monetarios asociados a la compra del producto se agregarán a los informes de la campaña.
Este punto final se puede utilizar con Productos y Variantes de productos. Si desea realizar un seguimiento de un Producto o Variante de producto existente, asegúrese de pasar el id, reference o sku de un registro existente. Si desea crear un nuevo Producto, debe pasar el parámetro product_parameters. De manera similar, si desea crear una nueva Variante de producto, asegúrese de pasar el product_variant_parameters en su lugar.
product.purchased
product.viewed
null.
cantidad proporcionada en formato ISO 4217. El valor predeterminado siempre es USD.
id, reference o sku de un objeto de producto existente. Opcional cuando pasa product_parameters o product_variant. Requerido al pasar product_variant_parameters.
product. El producto se va agregar y despues rastreado.
id, reference o sku de un objeto de variante de producto existente. Opcional cuando especifica product_variant_parameters.
product_variant. La variante de producto se creará y se realizará el seguimiento del evento. Al pasar este parámetro, asegúrese también de especificar el producto mediante el parámetro product.
session. Identificador único del objeto de perfil al que pertenece este evento. Si no se especifica explícitamente, el identificador de perfil se puede heredar cuando se especifica el parámetro session y la sesión ya está asociada a un perfil o se adjunta posteriormente a uno.
profile. Identificador del objeto de sesión al que pertenece este evento. Las sesiones son identificadores generados automáticamente a partir de los clics de los visitantes en enlaces cortos o de la librería Hellotext.js al realizar seguimientos de visitantes anónimos. Es una forma de rastrear eventos en el lado del cliente sin autenticar o revelar el identificador del perfil, lo que permite asociarlo más tarde a un perfil de forma segura en el lado del servidor. Más información sobre Sesiones.
created_at.
curl https://api.hellotext.com/v1/attribution/events \
-d action="product.purchased" \
-d product=vxqQJ3Yg \
-d session=2KAGgAgm \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"status": "received"
}
Eventos de reembolsos
Realiza un seguimiento de los eventos relacionados con los reembolsos solicitados por tus clientes. Las acciones disponibles son refund.requested y refund.received.
Los valores monetarios asociados a los reembolsos emitidos se agregarán a los informes de la campaña.
refund.received
refund.requested
null.
cantidad proporcionada en formato ISO 4217. El valor predeterminado siempre es USD.
session. Identificador único del objeto de perfil al que pertenece este evento. Si no se especifica explícitamente, el identificador de perfil se puede heredar cuando se especifica el parámetro session y la sesión ya está asociada a un perfil o se adjunta posteriormente a uno.
refund. El reembolsos se va agregar y despues rastreado.
profile. Identificador del objeto de sesión al que pertenece este evento. Las sesiones son identificadores generados automáticamente a partir de los clics de los visitantes en enlaces cortos o de la librería Hellotext.js al realizar seguimientos de visitantes anónimos. Es una forma de rastrear eventos en el lado del cliente sin autenticar o revelar el identificador del perfil, lo que permite asociarlo más tarde a un perfil de forma segura en el lado del servidor. Más información sobre Sesiones.
created_at.
curl https://api.hellotext.com/v1/attribution/events \
-d action="refund.added" \
-d refund=wx4Vn4no \
-d product=vxqQJ3Yg \
-d session=2KAGgAgm \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"status": "received"
}
Eventos personalizados
Hellotext te proporciona una lista de acciones pre-definidas para rastrear las interacciones más comunes de tus clientes como compras, visitas a tu sitio, productos agregados al carrito, formularios completados y más. Sin embargo, esto no siempre es suficiente y a veces necesitas mayor control y flexibilidad en definir acciones más específicas a las necesidades de tu negocio.
Es posible especificar cualquier nombre de acción personalizado al rastrear eventos siempre que el objeto de acción se haya creado previamente. Una vez creada la acción simplemente puedes utilizar su nombre para realizar un seguimiento.
Ten en cuenta que los valores monetarios transferidos a estos eventos se agregarán a los informes de la campaña como ventas.
Más sobre Acciones.
null.
cantidad proporcionada en formato ISO 4217. El valor predeterminado siempre es USD.
session. Identificador único del objeto de perfil al que pertenece este evento. Si no se especifica explícitamente, el identificador de perfil se puede heredar cuando se especifica el parámetro session y la sesión ya está asociada a un perfil o se adjunta posteriormente a uno.
profile. Identificador del objeto de sesión al que pertenece este evento. Las sesiones son identificadores generados automáticamente a partir de los clics de los visitantes en enlaces cortos o de la librería Hellotext.js al realizar seguimientos de visitantes anónimos. Es una forma de rastrear eventos en el lado del cliente sin autenticar o revelar el identificador del perfil, lo que permite asociarlo más tarde a un perfil de forma segura en el lado del servidor. Más información sobre Sesiones.
created_at.
curl https://api.hellotext.com/v1/attribution/events \
-d action="signup_form.completed" \
-d session=2KAGgAgm \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"status": "received"
}
Acciones
Hellotext proporciona un conjunto básico de acciones, perfecto para comenzar su próxima campaña de atribución. Pero, cuando surge la necesidad de rastrear diferentes acciones no proporcionadas por Hellotext, puede ampliar el conjunto de acciones disponibles creando sus propias acciones personalizadas.
Puede nombrar las acciones de la manera que desee. Recomendamos tomar un enfoque de puntos al nombrar sus acciones, para tenerlas agrupadas y con estados, por ejemplo, las acciones personalizadas pueden ser como las siguientes.
Ver Eventos personalizados para más información.
subscriber.signed_up
signup_form.completed
subscriber.voted
-
POST
v1/attribution/actions
-
GET
v1/attribution/actions/:id
-
PATCH
v1/attribution/actions/:id
-
DELETE
v1/attribution/actions/:id
-
GET
v1/attribution/actions
El objeto de acción
false. Si se establece en true, los eventos con este acción se pueden utilizar como una métrica para KPIs que se muestran en las Campañas y las Rutas.
action al momento de crear un evento. No se permiten nombres duplicados.
true. Los eventos pasivos son eventos que no afectan el orden de las conversaciones en la bandeja de entrada, cuando se graba un evento pasivo, la posición de la conversación no cambia. Los eventos pasivos no se muestran en la bandeja de entrada, solo se muestran en el registro de actividad de un perfil.
Los eventos no pasivos son eventos que afectan el orden de las conversaciones en la bandeja de entrada, cuando se registra un evento activo, la posición de la conversación se actualiza y se mueve a la parte superior para que pueda ser manejada. Los eventos no pasivos se registran en la Bandeja de entrada y en el Registro de actividad.
Generalmente, si la acción es importante (requiere una acción por parte de su equipo) y desea verla fácilmente en la bandeja de entrada cuando suceda, mantenga este atributo como
false. Sin embargo, si la acción no es importante, puede marcarla como pasiva.
{
"id": "Wvqz2qD1",
"type": "action",
"created_at": 1665684173,
"goal": false,
"name": "signup_form.completed",
"passive": true,
"title": "Signup-form completed"
}Crear una acción
Crea una nueva acción.
false. Si se establece en true, los eventos con este acción se pueden utilizar como una métrica para KPIs que se muestran en las Campañas y las Rutas.
action al momento de crear un evento. No se permiten nombres duplicados.
curl -X POST https://api.hellotext.com/v1/attribution/actions
-d name="signup_form.completed"
-d title="Signup-form completed"
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "Wvqz2qD1",
"type": "action",
"created_at": 1665684173,
"goal": false,
"name": "signup_form.completed",
"passive": true,
"title": "Signup-form completed"
}Obtener una acción
Obtener una acción existente.
curl -G https://api.hellotext.com/v1/attribution/actions/Wvqz2qD1 \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Modificar una acción
Modificar la acción especificada con la información proporcionada.
false. Si se establece en true, los eventos con este acción se pueden utilizar como una métrica para KPIs que se muestran en las Campañas y las Rutas.
action al momento de crear un evento. No se permiten nombres duplicados.
curl -X PATCH https://api.hellotext.com/v1/attribution/actions/:id
-d name="contact.subscribed"
-d title="Contact Subscribed"
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "Wvqz2qD1",
"type": "action",
"created_at": 1665684173,
"goal": false,
"name": "contact.subscribed",
"passive": true,
"title": "Contact Subscribed"
}Eliminar una acción
Elimina permanentemente la acción especificada.
Esta acción es irreversible. Al eliminar una acción, también se eliminarán todos los eventos rastreados asociados a ella. Tenga cuidado al usar este endpoint.
curl -X DELETE https://api.hellotext.com/v1/attribution/actions/Wvqz2qD1 \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"id": "Wvqz2qD1",
"type": "action",
"deleted": true
}Listar todas las acciones
Enumera las acciones existentes ordenadas por las más recientes. Los parámetros de paginación están disponibles en listas.
curl -G https://api.hellotext.com/v1/attribution/actions
-d limit=5
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"actions": [
{
"id": "Wvqz2qD1",
"type": "action",
"created_at": 1665684173,
"goal": false,
"name": "signup_form.completed",
"passive": true,
"title": "Signup-form completed"
},
"{...}",
"{...}"
]
}Apps
Los objetos de aplicación representan las aplicaciones propias o administradas con las que interactúa tu audiencia. Por ejemplo, estas podrían ser tus aplicaciones iOS o Android.
Puedes realizar un seguimiento de los eventos de tu audiencia que interactúan con tus aplicaciones. Por ejemplo, cuando alguien instala una aplicación, la elimina o gasta cualquier cantidad.
Conocer más Eventos de app.
POST /v1/attribution/apps
GET /v1/attribution/apps/:id
PATCH /v1/attribution/apps/:id
DELETE /v1/attribution/apps/:id
GET /v1/attribution/apps
El objeto de la aplicación
{
"id": "xnqJQ47v",
"type": "app",
"created_at": 1665684173
"image_url": "https://www.beautyandcare.com/apps/awesome.jpg",
"metadata": {},
"name": "Beauty & Care",
}
Crear una aplicación
Crea una nueva aplicación.
curl https://api.hellotext.com/v1/attribution/apps \
-d name="Beauty & Care" \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"id": "xnqJQ47v",
"type": "app",
"created_at": 1665684173
"image_url": null,
"metadata": {},
"name": "Beauty & Care",
}
Obtener una aplicación
Obtener una aplicación existente.
curl -G https://api.hellotext.com/v1/attribution/apps/xnqJQ47v \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Modiciar una aplicación
Modificar la aplicación especificada con la información proporcionada.
curl https://api.hellotext.com/v1/attribution/apps/xnqJQ47v \
-d name="Beauty & More" \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"id": "xnqJQ47v",
"type": "app",
"created_at": 1665684173
"image_url": null,
"metadata": {},
"name": "Beauty & More",
}
Eliminar una aplicación
Elimina permanentemente la aplicación especificada.
curl -X DELETE https://api.hellotext.com/v1/attribution/apps/xnqJQ47v \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"id": "xnqJQ47v",
"type": "app",
"deleted": true
}
Listar todas las aplicaciones
Enumera las aplicaciones existentes ordenadas por las más recientes. Los parámetros de paginación están disponibles en listas.
curl -G https://api.hellotext.com/v1/attribution/apps \
-d limit=5 \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"apps": [
{
"id": "xnqJQ47v",
"type": "app",
"created_at": 1665684173
"image_url": "https://www.beautyandcare.com/apps/awesome.jpg",
"metadata": {},
"name": "Beauty & Care",
},
{...},
{...}
]
}
Carts
Los objetos de carrito representan objetos de carrito de compras que se pueden utilizar para determinar qué elementos tiene el perfil en el carrito en un momento determinado.
Los objetos de carrito actúan como grupos lógicos donde puedes agrupar varios productos agregados a un carrito juntos.
Puedes rastrear cuándo se agregan elementos al carrito, se eliminan del carrito o cuándo se abandonó el carrito.
Conocer más Eventos de carrito.
-
POST
v1/attribution/carts
-
GET
v1/attribution/carts/:id
-
PATCH
v1/attribution/carts/:id
-
DELETE
v1/attribution/carts/:id
-
GET
v1/attribution/carts
El objeto de carrito
{
"id": "wx4Vn4no",
"type": "cart",
"created_at": 1665684173,
"items": [
{
"id": "wx4Vn4no",
"type": "cart_item",
"created_at": 1665684173,
"price": {
"amount": "100.00",
"converted_amount": "100.00",
"converted_currency": "EUR",
"currency": "USD"
},
"product": "vxqQJ3Yg",
"quantity": 1
},
"{...}",
"{...}"
],
"metadata": {
},
"profile": "MzYwlE50",
"reference": "ABC123",
"session": "Vdqlg4nL",
"source": null
}Crear un carrito
Crea un nuevo carrito.
session.
profile." "Se puede usar para asociar el carrito con un perfil indefinido. Y luego adjuntar el carrito al perfil una vez que se conozca el perfil."
curl -X POST https://api.hellotext.com/v1/attribution/carts
-d metadata[attribute1]=value1
-d metadata[attribute2]=value2
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "wx4Vn4no",
"type": "cart",
"created_at": 1665684173,
"items": [
{
"id": "wx4Vn4no",
"type": "cart_item",
"created_at": 1665684173,
"price": {
"amount": "100.00",
"converted_amount": "100.00",
"converted_currency": "EUR",
"currency": "USD"
},
"product": "vxqQJ3Yg",
"quantity": 1
},
"{...}",
"{...}"
],
"metadata": {
"attribute1": "value1",
"attribute2": "value2"
},
"profile": "MzYwlE50",
"reference": "ABC123",
"session": "Vdqlg4nL",
"source": null
}Obtener un carrito
Obtener un carrito existente.
curl -G https://api.hellotext.com/v1/attribution/carts/wx4Vn4no
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."Modificar un carrito
Modificar el carrito especificado con la información proporcionada.
[] eliminará todos los elementos del carrito." "Ignorar el parámetro no cambiará los elementos actuales en el carrito."
session.
profile." "Se puede usar para asociar el carrito con un perfil indefinido. Y luego adjuntar el carrito al perfil una vez que se conozca el perfil."
curl -X PATCH https://api.hellotext.com/v1/attribution/carts/wx4Vn4no
-d metadata[attribute1]=value1
-d metadata[attribute2]=value2
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "wx4Vn4no",
"type": "cart",
"created_at": 1665684173,
"items": [
{
"id": "wx4Vn4no",
"type": "cart_item",
"created_at": 1665684173,
"price": {
"amount": "100.00",
"converted_amount": "100.00",
"converted_currency": "EUR",
"currency": "USD"
},
"product": "vxqQJ3Yg",
"quantity": 1
},
"{...}",
"{...}"
],
"metadata": {
"attribute1": "value1",
"attribute2": "value2"
},
"profile": "MzYwlE50",
"reference": "ABC123",
"session": "Vdqlg4nL",
"source": null
}Eliminar un carrito
Elimina permanentemente el carrito especificado.
curl -X DELETE https://api.hellotext.com/v1/attribution/carts/wx4Vn4no
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "wx4Vn4no",
"type": "cart",
"deleted": true
}Listar todos los carros
Enumera los carritos existentes ordenados por los más recientes. Los parámetros de paginación están disponibles en listas.
curl -G https://api.hellotext.com/v1/attribution/carts
-d limit=5
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"carts": [
{
"id": "wx4Vn4no",
"type": "cart",
"created_at": 1665684173,
"items": [
{
"id": "wx4Vn4no",
"type": "cart_item",
"created_at": 1665684173,
"price": {
"amount": "100.00",
"converted_amount": "100.00",
"converted_currency": "EUR",
"currency": "USD"
},
"product": "vxqQJ3Yg",
"quantity": 1
},
"{...}",
"{...}"
],
"metadata": {
},
"profile": "MzYwlE50",
"reference": "ABC123",
"session": "Vdqlg4nL",
"source": null
},
"{...}",
"{...}"
]
}Eventos
Los eventos representan las acciones individuales de tus clientes que deseas rastrear. Todos los eventos siempre se asocian a un perfil a través de un session o perfil.
Un evento siempre requiere una acción de la que deseas realizar un seguimiento. Consulta la sección Seguimiento para obtener más información sobre las diferentes formas de realizar un seguimiento de los eventos.
POST /v1/attribution/events
GET /v1/attribution/events/:id
PATCH /v1/attribution/events/:id
DELETE /v1/attribution/events/:id
GET /v1/attribution/events
El objeto de evento
null.
cantidad proporcionada en formato ISO 4217. El valor predeterminado siempre es USD.
session. Identificador único del objeto de perfil al que pertenece este evento. Si no se especifica explícitamente, el identificador de perfil se puede heredar cuando se especifica el parámetro session y la sesión ya está asociada a un perfil o se adjunta posteriormente a uno.
profile. Identificador del objeto de sesión al que pertenece este evento. Las sesiones son identificadores generados automáticamente a partir de los clics de los visitantes en enlaces cortos o de la librería Hellotext.js al realizar seguimientos de visitantes anónimos. Es una forma de rastrear eventos en el lado del cliente sin autenticar o revelar el identificador del perfil, lo que permite asociarlo más tarde a un perfil de forma segura en el lado del servidor. Más información sobre Sesiones.
created_at.
{
"id": "xnqJQ47v",
"type": "event",
"action": {
"id": "Wvqz2qD1",
"name": "order.confirmed",
"title": "Product purchased"
},
"amount": 199.95,
"converted_amount": "19.90",
"converted_amount_currency": "EUR",
"created_at": 1665684173,
"currency": "USD",
"metadata": {},
"profile": "MzYwlE50",
"session": "Vdqlg4nL",
"trackable": {
"id": "ro4a731w",
"type": "order",
"amount": 199.95,
"currency": "USD",
"product_ids": ["xnqJQ47v"]
},
"tracked_at": "1665684173",
}
Obtener un evento
Obtener un evento existente.
curl -G https://api.hellotext.com/v1/attribution/events/xnqJQ47v \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Modificar un evento
Modificar el evento especificado con la información proporcionada.
null.
cantidad proporcionada en formato ISO 4217. El valor predeterminado siempre es USD.
session. Identificador único del objeto de perfil al que pertenece este evento. Si no se especifica explícitamente, el identificador de perfil se puede heredar cuando se especifica el parámetro session y la sesión ya está asociada a un perfil o se adjunta posteriormente a uno.
profile. Identificador del objeto de sesión al que pertenece este evento. Las sesiones son identificadores generados automáticamente a partir de los clics de los visitantes en enlaces cortos o de la librería Hellotext.js al realizar seguimientos de visitantes anónimos. Es una forma de rastrear eventos en el lado del cliente sin autenticar o revelar el identificador del perfil, lo que permite asociarlo más tarde a un perfil de forma segura en el lado del servidor. Más información sobre Sesiones.
created_at.
curl https://api.hellotext.com/v1/attribution/events/xnqJQ47v \
-d amount=295.00 \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"id": "xnqJQ47v",
"type": "event",
"action": {
"id": "Wvqz2qD1",
"name": "order.confirmed",
"title": "Product purchased"
},
"amount": 295.00,
"converted_amount": "19.90",
"converted_amount_currency": "EUR",
"created_at": 1665684173,
"currency": "USD",
"metadata": {},
"profile_id": "MzYwlE50",
"session_id": "Vdqlg4nL",
"trackable": {
"id": "ro4a731w",
"type": "order",
"amount": 199.95,
"currency": "USD",
"product_ids": ["xnqJQ47v"]
},
"tracked_at": "1665684173",
}
Eliminar un evento
Elimina permanentemente el evento especificado.
curl -X DELETE https://api.hellotext.com/v1/attribution/events/xnqJQ47v \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"id": "xnqJQ47v",
"type": "event",
"deleted": true
}
Listar todos los eventos
Enumera los eventos existentes ordenados por los más recientes. Los parámetros de paginación están disponibles en listas.
curl -G https://api.hellotext.com/v1/attribution/events \
-d limit=5 \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"events": [
{
"id": "xnqJQ47v",
"type": "event",
"action": {
"id": "Wvqz2qD1",
"name": "order.confirmed",
"title": "Product purchased"
},
"amount": 199.95,
"converted_amount": "19.90",
"converted_amount_currency": "EUR",
"created_at": 1665684173
"currency": "USD",
"metadata": {},
"profile": "MzYwlE50",
"session": "Vdqlg4nL",
"trackable": {
"id": "ro4a731w",
"type": "order",
"amount": 199.95,
"currency": "USD",
"product_ids": ["xnqJQ47v"]
},
"tracked_at": "1665684173"
},
{...},
{...}
]
}
Formularios
Los objetos de formulario representan objetos de formulario que puede usar cuando realizas un seguimiento de acciones como form.completed.
Los objetos de formularios actúan como grupos lógicos donde puede agrupar varias acciones en el mismo objeto para obtener mejores informes.
POST /v1/attribution/forms
GET /v1/attribution/forms/:id
PATCH /v1/attribution/forms/:id
DELETE /v1/attribution/forms/:id
GET /v1/attribution/forms
El objeto de formulario
{
"id": "O8lOzkwa",
"type": "form",
"created_at": 1665684173
"metadata": {},
"name": "Sign-Up Form",
}
Crear un formulario
Crea un nuevo formulario.
curl https://api.hellotext.com/v1/attribution/forms \
-d name="Sign-Up Form" \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"id": "O8lOzkwa",
"type": "form",
"created_at": 1665684173
"metadata": {}
"name": "Sign-Up Form",
}
Obtener un formulario
Obtener un formulario existente.
curl -G https://api.hellotext.com/v1/attribution/forms/O8lOzkwa \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Modificar un formulario
Modificar el formulario especificado con la información proporcionada.
curl https://api.hellotext.com/v1/attribution/forms/O8lOzkwa \
-d name="Completion Form" \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"id": "O8lOzkwa",
"type": "form",
"created_at": 1665684173
"metadata": {},
"name": "Completion Form",
}
Eliminar un formulario
Elimina permanentemente el formulario especificado.
curl -X DELETE https://api.hellotext.com/v1/attribution/forms/O8lOzkwa \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"id": "O8lOzkwa",
"type": "form",
"deleted": true
}
Listar todas las formas
Enumera los formularios existentes ordenados por los más recientes. Los parámetros de paginación están disponibles en listas.
curl -G https://api.hellotext.com/v1/attribution/forms \
-d limit=5 \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"forms": [
{
"id": "O8lOzkwa",
"type": "form",
"created_at": 1665684173
"metadata": {},
"name": "Sign-Up Form",
},
{...},
{...}
]
}
El objeto Pedido
Los ordenes representan grupos de productos que puedes usar al rastrear los eventos order.placed, order.confirmed, order.shipped, order.cancelled y order.delivered.
-
POST
v1/attribution/orders
-
GET
v1/attribution/orders/:id
-
PATCH
v1/attribution/orders/:id
-
DELETE
v1/attribution/orders/:id
-
GET
v1/attribution/orders
El objeto Pedido
collect cuando los clientes compran directamente en la tienda o recogen en la tienda y deliver cuando se envía el paquete a la dirección del cliente. Este atributo no está establecido de forma predeterminada.
collect
deliver
{
"id": "ro4a731w",
"type": "order",
"created_at": 1665684173,
"delivery": "deliver",
"items": [
{
"id": "vxqQJ3Yg",
"type": "order_item",
"price": {
"amount": "395.00",
"currency": "USD",
"converted_amount": "19.90",
"converted_currency": "EUR"
},
"product": "vxqQJ3Yg",
"quantity": 1
}
],
"metadata": {
},
"reference": "1234",
"source": null,
"total": {
"amount": "395.00",
"converted_amount": "19.90",
"converted_amount_currency": "EUR",
"currency": "USD"
}
}Crear un Orden
Crea un nuevo orden.
collect cuando los clientes compran directamente en la tienda o recogen en la tienda y deliver cuando se envía el paquete a la dirección del cliente. Este atributo no está establecido de forma predeterminada.
collect
deliver
curl -X POST https://api.hellotext.com/v1/attribution/orders
-d product="vxqQJ3YQ"
-d name="Yeezy boost 350 v2"
-d sku="1234567890"
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "ro4a731w",
"type": "order",
"created_at": 1665684173,
"delivery": "deliver",
"items": [
{
"id": "vxqQJ3Yg",
"type": "order_item",
"price": {
"amount": "395.00",
"currency": "USD",
"converted_amount": "19.90",
"converted_currency": "EUR"
},
"product": "vxqQJ3Yg",
"quantity": 1
}
],
"metadata": {
},
"reference": "1234",
"source": null,
"total": {
"amount": "395.00",
"converted_amount": "19.90",
"converted_amount_currency": "EUR",
"currency": "USD"
},
"product": "vxqQJ3YQ",
"name": "Yeezy boost 350 v2",
"sku": "1234567890"
}Recuperar un Orden
Recupera los detalles de un orden existente.
curl -G https://api.hellotext.com/v1/attribution/orders/vxqQJ3Yg
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "ro4a731w",
"type": "order",
"created_at": 1665684173,
"delivery": "deliver",
"items": [
{
"id": "vxqQJ3Yg",
"type": "order_item",
"price": {
"amount": "395.00",
"currency": "USD",
"converted_amount": "19.90",
"converted_currency": "EUR"
},
"product": "vxqQJ3Yg",
"quantity": 1
}
],
"metadata": {
},
"reference": "1234",
"source": null,
"total": {
"amount": "395.00",
"converted_amount": "19.90",
"converted_amount_currency": "EUR",
"currency": "USD"
}
}Actualizar un Orden
Actualiza un orden existente.
collect cuando los clientes compran directamente en la tienda o recogen en la tienda y deliver cuando se envía el paquete a la dirección del cliente. Este atributo no está establecido de forma predeterminada.
collect
deliver
curl -X PATCH https://api.hellotext.com/v1/attribution/orders/vxqQJ3Yg
-d name="Yeezy boost 350 v2"
-d sku="5678"
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "vxqQJ3YQ",
"type": "order",
"created_at": 1665684173,
"delivery": "deliver",
"items": [
{
"id": "vxqQJ3Yg",
"type": "order_item",
"price": {
"amount": "395.00",
"currency": "USD",
"converted_amount": "19.90",
"converted_currency": "EUR"
},
"product": "vxqQJ3Yg",
"quantity": 1
}
],
"metadata": {
},
"reference": "1234",
"source": null,
"total": {
"amount": "395.00",
"converted_amount": "19.90",
"converted_amount_currency": "EUR",
"currency": "USD"
},
"name": "Yeezy boost 350 v2",
"sku": "5678"
}Eliminar un Orden
Elimina un orden.
curl -X DELETE https://api.hellotext.com/v1/attribution/orders/vxqQJ3Yg
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "vxqQJ3Yg",
"type": "order",
"deleted": true
}Listar todos los Ordenes
Enumera las órdenes existentes ordenados por los más recientes. Los parámetros de paginación están disponibles en listas.
curl -G https://api.hellotext.com/v1/attribution/orders
-d limit=5
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"orders": [
{
"id": "ro4a731w",
"type": "order",
"created_at": 1665684173,
"delivery": "deliver",
"items": [
{
"id": "vxqQJ3Yg",
"type": "order_item",
"price": {
"amount": "395.00",
"currency": "USD",
"converted_amount": "19.90",
"converted_currency": "EUR"
},
"product": "vxqQJ3Yg",
"quantity": 1
}
],
"metadata": {
},
"reference": "1234",
"source": null,
"total": {
"amount": "395.00",
"converted_amount": "19.90",
"converted_amount_currency": "EUR",
"currency": "USD"
}
},
"{...}",
"{...}"
]
}El Elemento de la orden.
Describe un producto en un orden.
-
POST
v1/attribution/orders/:order/items
-
PATCH
v1/attribution/orders/:order/items/:id
-
DELETE
v1/attribution/orders/:order/items/:id
El Elemento de la orden.
{
"id": "vxqQJ3Yg",
"type": "order_item",
"price": {
"amount": "395.00",
"currency": "USD",
"converted_amount": "19.90",
"converted_currency": "EUR"
},
"product": "vxqQJ3Yg",
"quantity": 1
}Crear un Elemento del orden
Agrega un producto a un orden.
El total del orden se actualizará automáticamente para reflejar el nuevo artículo.
product.
id, reference o sku) de un producto o variante de producto.
curl -X POST https://api.hellotext.com/v1/attribution/orders/vxqQJ3YQ/items
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "vxqQJ3Yg",
"type": "order_item",
"price": {
"amount": "395.00",
"currency": "USD",
"converted_amount": "19.90",
"converted_currency": "EUR"
},
"product": "vxqQJ3Yg",
"quantity": 1,
"order": "vxqQJ3YQ"
}Actualizar un Elemento del orden
Actualiza los atributos de un artículo específico.
El total del orden se actualizará automáticamente para reflejar los cambios.
curl -X PATCH https://api.hellotext.com/v1/attribution/orders/vxqQJ3YQ/items/xqQJ3YQ
-d quantity=5
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "xqQJ3YQ",
"type": "order_item",
"price": {
"amount": "395.00",
"currency": "USD",
"converted_amount": "19.90",
"converted_currency": "EUR"
},
"product": "vxqQJ3Yg",
"quantity": 5,
"order": "vxqQJ3YQ"
}Eliminar un Elemento del orden
Elimina un producto de un orden.
El total del orden se actualizará automáticamente para reflejar el artículo eliminado.
curl -X DELETE https://api.hellotext.com/v1/attribution/orders/vxqQJ3Yg/items/vxqQJ3Yg
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "vxqQJ3Yg",
"type": "order_item",
"deleted": true
}Productos
Los objetos de producto representan productos que puedes usar para rastrear acciones a través de su ciclo de vida, como producto.comprado y producto.visto o carrito.agregado y carrito.eliminado.
Los objetos de producto actúan como grupos lógicos donde puedes agrupar múltiples acciones al mismo objeto para una mejor presentación de informes.
-
POST
v1/attribution/products
-
GET
v1/attribution/products/:id
-
PATCH
v1/attribution/products/:id
-
DELETE
v1/attribution/products/:id
-
GET
v1/attribution/products
The Product Object
{
"id": "vxqQJ3Yg",
"type": "product",
"brand": "Adidas",
"categories": [
"shoes"
],
"collection": [
"350 v2"
],
"created_at": 1665684173,
"metadata": {
},
"name": "Yeezy Boost 350 v2",
"price": {
"amount": 220.0,
"converted_amount": 220.0,
"converted_currency": "EUR",
"currency": "USD"
},
"reference": null,
"sku": "1234567890",
"source": null,
"tags": [
"Sneakers"
],
"variants": [
{
"id": "vxqQJ3Yg",
"type": "product_variant",
"created_at": 1665684173,
"image_url": "https://www.primesneakers.com/products/yeezy-350-v2.jpg",
"metadata": {
},
"name": "Yeezy Boost 350 v2",
"price": {
"amount": 220.0,
"converted_amount": 220.0,
"converted_currency": "EUR",
"currency": "USD"
},
"product": "vxqQJ3YQ",
"reference": null,
"sku": "1234567890",
"source": null
},
"{...}",
"{...}"
]
}Crear un producto
Crea un nuevo producto.
curl -X POST https://api.hellotext.com/v1/attribution/products
-d name="Sign-Up Form"
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "vxqQJ3Yg",
"type": "product",
"brand": "Adidas",
"categories": [
"shoes"
],
"collection": [
"350 v2"
],
"created_at": 1665684173,
"metadata": {
},
"name": "Sign-Up Form",
"price": {
"amount": 220.0,
"converted_amount": 220.0,
"converted_currency": "EUR",
"currency": "USD"
},
"reference": null,
"sku": "1234567890",
"source": null,
"tags": [
"Sneakers"
],
"variants": [
{
"id": "vxqQJ3Yg",
"type": "product_variant",
"created_at": 1665684173,
"image_url": "https://www.primesneakers.com/products/yeezy-350-v2.jpg",
"metadata": {
},
"name": "Yeezy Boost 350 v2",
"price": {
"amount": 220.0,
"converted_amount": 220.0,
"converted_currency": "EUR",
"currency": "USD"
},
"product": "vxqQJ3YQ",
"reference": null,
"sku": "1234567890",
"source": null
},
"{...}",
"{...}"
]
}Obtener un producto
Obtener un producto existente. Puedes usar el parámetro id, reference o sku para recuperar un producto.
curl -G https://api.hellotext.com/v1/attribution/products/vxqQJ3Yg
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."Modificar un producto
Modificar el producto especificado con la información proporcionada. Puedes usar el parámetro id, reference o sku para actualizar un producto.
curl -X PATCH https://api.hellotext.com/v1/attribution/products/:id
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "vxqQJ3Yg",
"type": "product",
"brand": "Adidas",
"categories": [
"shoes"
],
"collection": [
"350 v2"
],
"created_at": 1665684173,
"metadata": {
},
"name": "Yeezy Boost 350 v2",
"price": {
"amount": 220.0,
"converted_amount": 220.0,
"converted_currency": "EUR",
"currency": "USD"
},
"reference": null,
"sku": "1234567890",
"source": null,
"tags": [
"Sneakers"
],
"variants": [
{
"id": "vxqQJ3Yg",
"type": "product_variant",
"created_at": 1665684173,
"image_url": "https://www.primesneakers.com/products/yeezy-350-v2.jpg",
"metadata": {
},
"name": "Yeezy Boost 350 v2",
"price": {
"amount": 220.0,
"converted_amount": 220.0,
"converted_currency": "EUR",
"currency": "USD"
},
"product": "vxqQJ3YQ",
"reference": null,
"sku": "1234567890",
"source": null
},
"{...}",
"{...}"
]
}Eliminar un producto
Elimina permanentemente el producto especificado. Puedes usar el parámetro id, reference o sku para eliminar un producto.
curl -X DELETE https://api.hellotext.com/v1/attribution/products/vxqQJ3Yg
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "vxqQJ3Yg",
"type": "product",
"deleted": true
}Listar todos los productos
Enumera los productos existentes ordenados por los más recientes. Los parámetros de paginación están disponibles en listas.
curl -G https://api.hellotext.com/v1/attribution/products
-d limit=5
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"products": [
{
"id": "vxqQJ3Yg",
"type": "product",
"brand": "Adidas",
"categories": [
"shoes"
],
"collection": [
"350 v2"
],
"created_at": 1665684173,
"metadata": {
},
"name": "Yeezy Boost 350 v2",
"price": {
"amount": 220.0,
"converted_amount": 220.0,
"converted_currency": "EUR",
"currency": "USD"
},
"reference": null,
"sku": "1234567890",
"source": null,
"tags": [
"Sneakers"
],
"variants": [
{
"id": "vxqQJ3Yg",
"type": "product_variant",
"created_at": 1665684173,
"image_url": "https://www.primesneakers.com/products/yeezy-350-v2.jpg",
"metadata": {
},
"name": "Yeezy Boost 350 v2",
"price": {
"amount": 220.0,
"converted_amount": 220.0,
"converted_currency": "EUR",
"currency": "USD"
},
"product": "vxqQJ3YQ",
"reference": null,
"sku": "1234567890",
"source": null
},
"{...}",
"{...}"
]
},
"{...}",
"{...}"
]
}Variantes de Producto
El objeto Variante de Producto representa una variación específica de un producto. Por ejemplo, un producto con un tamaño y color puede tener múltiples variantes. Cada variante puede tener un precio, SKU o referencia diferente.
Las variantes pueden crearse directamente al crear un Producto a través del parámetro variants. O al actualizar un producto pasando el parámetro new_variants.
-
POST
v1/attribution/products/:product/variants
-
GET
v1/attribution/variants/:id
-
PATCH
v1/attribution/variants/:id
-
DELETE
v1/attribution/variants/:id
El objeto Variante de Producto
{
"id": "vxqQJ3Yg",
"type": "product_variant",
"created_at": 1665684173,
"image_url": "https://www.primesneakers.com/products/yeezy-350-v2.jpg",
"metadata": {
},
"name": "Yeezy Boost 350 v2",
"price": {
"amount": 220.0,
"converted_amount": 220.0,
"converted_currency": "EUR",
"currency": "USD"
},
"product": "vxqQJ3YQ",
"reference": null,
"sku": "1234567890",
"source": null
}Crear una Variante de Producto
Crea una nueva Variante de Producto.
Asegúrate de reemplazar :product con el id, reference o sku del Producto padre. Intentamos encontrar el producto padre primero por el id, luego por la referencia y finalmente por el sku. Cuando no se encuentra ningún producto padre, se devolverá un error 404.
curl -X POST https://api.hellotext.com/v1/attribution/products/vxqQJ3YQ/variants
-d name="Yeezy boost 350 v2"
-d sku="1234567890"
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "vxqQJ3Yg",
"type": "product_variant",
"created_at": 1665684173,
"image_url": "https://www.primesneakers.com/products/yeezy-350-v2.jpg",
"metadata": {
},
"name": "Yeezy boost 350 v2",
"price": {
"amount": 220.0,
"converted_amount": 220.0,
"converted_currency": "EUR",
"currency": "USD"
},
"product": "vxqQJ3YQ",
"reference": null,
"sku": "1234567890",
"source": null
}Recuperar una Variante de Producto
Recupera los detalles de una Variante de Producto existente. Puedes obtener una Variante de Producto por su id, reference o sku.
curl -G https://api.hellotext.com/v1/attribution/variants/vxqQJ3Yg
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."Actualizar una Variante de Producto
Actualiza la Variante de Producto especificada. Puedes actualizar una Variante de Producto por su id, reference o sku.
curl -X PATCH https://api.hellotext.com/v1/attribution/variants/vxqQJ3Yg
-d name="Yeezy boost 350 v2"
-d sku="5678"
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "vxqQJ3YQ",
"type": "product_variant",
"created_at": 1665684173,
"image_url": "https://www.primesneakers.com/products/yeezy-350-v2.jpg",
"metadata": {
},
"name": "Yeezy boost 350 v2",
"price": {
"amount": 220.0,
"converted_amount": 220.0,
"converted_currency": "EUR",
"currency": "USD"
},
"product": "vxqQJ3YQ",
"reference": null,
"sku": "5678",
"source": null
}Eliminar una Variante de Producto
Elimina la Variante de Producto especificada. Puedes eliminar una Variante de Producto por su id, reference o sku.
curl -X DELETE https://api.hellotext.com/v1/attribution/variants/vxqQJ3Yg
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."{
"id": "vxqQJ3Yg",
"type": "product_variant",
"deleted": true
}Reembolsos
Los objetos de reembolso representan reembolsos que puede utilizar para realizar un seguimiento de las acciones a lo largo de su ciclo de vida, como refund.requested y refund.received.
Los objetos de reembolso actúan como grupos lógicos en los que puede agrupar varias acciones en el mismo objeto para obtener mejores informes.
POST /v1/attribution/refunds
GET /v1/attribution/refunds/:id
PATCH /v1/attribution/refunds/:id
DELETE /v1/attribution/refunds/:id
GET /v1/attribution/refunds
El objeto del reembolso
order o product asociado al reembolso. Este atributo es opcional y por defecto su valor es null.
{
"id": "w83Pj4PY",
"type": "refund",
"created_at": 1665684173
"metadata": {},
"profile": null,
"reference": null,
"refundable": {
"id": "ro4a731w",
"type": "order",
"amount": "199.95",
"created_at": 1665684173,
"currency": "USD",
"metadata": {}
},
"source": null,
"total": {
"amount": "199.95",
"converted_amount": "199.95",
"converted_currency": "EUR",
"currency": "USD",
}
}
Crear un reembolso
Crea un nuevo reembolso.
refundable.
refundable.
curl https://api.hellotext.com/v1/attribution/refunds \
-d amount=19.90 \
-d order=ro4a731w \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"id": "w83Pj4PY",
"type": "refund",
"created_at": 1665684173
"metadata": {},
"profile": null,
"reference": null,
"refundable": {
"id": "ro4a731w",
"type": "order",
"amount": "199.95",
"created_at": 1665684173,
"currency": "USD",
"metadata": {}
},
"source": null,
"total": {
"amount": "199.95",
"converted_amount": "199.95",
"converted_currency": "EUR",
"currency": "USD",
}
}
Obtener un reembolso
Obtener un reembolso existente.
curl -G https://api.hellotext.com/v1/attribution/refunds/w83Pj4PY \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
Modificar un reembolso
Modificar el reembolso especificado con la información proporcionada.
refundable.
refundable.
curl https://api.hellotext.com/v1/attribution/refunds/w83Pj4PY \
-d amount=24.90 \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"id": "w83Pj4PY",
"type": "refund",
"created_at": 1665684173
"metadata": {},
"profile": null,
"reference": null,
"refundable": {
"id": "ro4a731w",
"type": "order",
"amount": "199.95",
"created_at": 1665684173,
"currency": "USD",
"metadata": {}
},
"source": null,
"total": {
"amount": "199.95",
"converted_amount": "199.95",
"converted_currency": "EUR",
"currency": "USD",
}
}
Eliminar un reembolso
Elimina permanentemente el reembolso especificado.
curl -X DELETE https://api.hellotext.com/v1/attribution/refunds/w83Pj4PY \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"id": "w83Pj4PY",
"type": "refund",
"deleted": true
}
Listar todos los reembolsos
Enumera los reembolsos existentes ordenados por los más recientes. Los parámetros de paginación están disponibles en listas.
curl -G https://api.hellotext.com/v1/attribution/refunds \
-d limit=5 \
-H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
"refunds": [
{
"id": "w83Pj4PY",
"type": "refund",
"created_at": 1665684173
"metadata": {},
"profile": null,
"reference": null,
"refundable": {
"id": "ro4a731w",
"type": "order",
"amount": "199.95",
"created_at": 1665684173,
"currency": "USD",
"metadata": {}
},
"source": null,
"total": {
"amount": "199.95",
"converted_amount": "199.95",
"converted_currency": "EUR",
"currency": "USD",
}
},
{...},
{...}
]
}
Sesiones
Las sesiones son identificadores únicos que se generan cuando los visitantes hacen clic en enlaces cortos y se adjuntan a la URL de destino como un parámetro GET llamado hello_session. Puedes pensar en una sesión compartiendo el mismo significado ya familiar de los navegadores web: representa un navegador de un visitante activo y es específico a un dispositivo.
Al realizar seguimientos de eventos con el identificador de sesión, estos mantendrán una asociación automática con el perfil del cliente que hizo clic en el enlace corto, agregando los eventos a su historial de actividades y al informe de la campaña o ruta donde estuvo presente el mensaje con el enlace corto.
Al realizar un seguimiento de los eventos del lado del cliente con la biblioteca Hellotext.js, no es necesario especificar explícitamente el identificador de la sesión, ya que la biblioteca se encargará de ello de manera automática.
Para mejorar la seguridad y la privacidad, desaconsejamos revelar el identificador del perfil directamente en el navegador. Debido a esto, la biblioteca Hellotext.js solo acepta realizar un seguimiento de los eventos que especifican un session y no un perfil directamente.
También es posible rastrear eventos para visitantes no identificados. La biblioteca Hellotext.js crea un nuevo identificador de sesión para cada nuevo visitante cuando no lo encuentra definido como parámetro. Puedes almacenar este identificador de sesión y luego adjuntar el perfil cuando se conozca, por ejemplo, cuando el visitante inicia sesión en la tienda, realiza una orden o se suscribe ingresando su número de teléfono.
PATCH /v1/sessions/:id
Attach session
Una vez conocido el perfil, adjúntalo a la sesión para que todos sus eventos rastreados pasen a formar parte de su historial de actividades.
Si también deseas cambiar la sesión a un perfil diferente, configura el nuevo identificador de perfil en el parámetro profile y la sesión se asignará al nuevo perfil.
Todos los carritos asociados con una sesión se asignarán al perfil al que adjunta la sesión.
- Producto
- ¿Por qué Hellotext?
- Recursos
- Centro de Ayuda
- Preguntas Frecuentes
- Soporte
- Desarrolladores
- Recursos
- Referencia de la API
- Hellotext.js
- Empresa
- Acerca
- Carreras
- Contáctanos
- Mantente al día en eCommerce Marketing
- Suscríbete para recibir info y actualizaciones de Hellotext
