Ingresar Obtener demo

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.

Puedes 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 -G 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 error 422 y un objeto JSON de errores, incluida una colección de errores que incluye el tipo y la descripción.

Atributos
type
string
Código en formato string que representa el error.
message
string
Descripción detallada del error.
parameter
string
Nombre del parámetro asociado al error.
400 Bad Request
A menudo falta un parámetro requerido.
401 Unauthorized
No hay clave de API válida.
404 Not Found
El recurso o objeto solicitado no existe.
422 Request Failed
Los parámetros eran válidos pero la solicitud falló.
500, 502, 503, 504 Server errors
Algo salió mal.
ambiguous_parameter
Se proporcionaron uno o más parámetros posibles para el mismo rol. Especifica al menos uno de los valores posibles.
invalid
El valor que proporcionaste para el parámetro no es correcto. Por favor, verifica la documentación para obtener el valor correcto.
not_allowed
La operación no está permitida. Generalmente porque el objeto se encuentra en un estado que no permite la acción.
not_found
Este objeto no fue encontrado. Tal vez fue borrado.
object_invalid
Se debe proporcionar al menos uno de los parámetros opcionales.
parameter_invalid_empty
Uno o más parámetros obligatorios están vacíos.
parameter_missing
Este parámetro es requerido.
parameter_not_unique
El valor debe ser único y ya está presente en otro objeto del mismo tipo.
session_assigned_to_another_profile
Esta sesión ha sido asignada a otro perfil. No se puede usar para rastrear eventos para el perfil actual.
undefined_property
Intentó establecer una propiedad en un perfil que no existía.
{
  "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.

Parámetros
starting_after
string
Muestra los resultados después (más antiguos) que el identificador proporcionado.
ending_before
string
Muestra los resultados antes (más recientes) que el identificador proporcionado.
limit
integer
Limita la cantidad de resultados que se mostrarán. El valor predeterminado es 25. El máximo es 100. 
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

Atributos
id
String
Identificador único del objeto.
type
Type
Tipo de objeto. Esto es siempre profile.
blocked
Boolean
¿Este perfil ha sido bloqueado o no? Es true o false.
created_at
Epoch
Fecha de creación del objeto.
emails
array
Colección con todos los correos electrónicos en este perfil establecidos como propiedades de tipo email
first_name
String
Nombre del cliente representado en el perfil.
last_name
String
Apellido del cliente representado en el perfil.
lists
array
Colección con todas las listas de las que forma parte este perfil. Mostrar atributos
phones
array
Una colección de todos los números de teléfono verificados o no verificados en este perfil establecidos como propiedades del tipo phone, enumerados en formato e164.
properties
array
Array de hashes que representan los objetos de identidades del perfil. Por ejemplo números de teléfono, identidades de Mercado Libre. Mostrar atributos
state
Enum
El estado actual del perfil que indica si el perfil está suscrito explícitamente para recibir contenido promocional o no desea recibir ninguna comunicación promocional.
Valores enum posibles
unconfirmed Defecto
subscribed
unsubscribed
verified_emails
array
Una colección de todos los correos electrónicos verificados del perfil.
verified_phones
array
Una colección de todos los números de teléfono verificados del perfil. 
{
  "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.

Parámetros
address
hash
Establece la dirección para la propiedad address predeterminada. Puedes 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[name]
String
Establece la dirección para la propiedad 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
String
Establece la dirección de correo electrónico para la propiedad email predeterminada.
email[name]
String
Establece la dirección de correo electrónico para la propiedad 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.
first_name
String
Nombre del cliente representado en el perfil.
last_name
String
Apellido del cliente representado en el perfil.
lists
array
Una colección de nombres de lista a la que se agregará este perfil. Se crearán nuevas listas cuando no exista una lista con este nombre.
phone
String
Establece el número de teléfono para la propiedad 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[name]
String
Establece el número de teléfono para la propiedad 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[name]
String
Establece un valor de propiedad pasando el nombre de la propiedad, por ejemplo 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_by_id[id]
String
Establece un valor de propiedad pasando el id de la propiedad, por ejemplo, property[gVlpOkwJ]=MiValor.
subscribe
Boolean
Utiliza el valor 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.

Parámetros
address
hash
Establece la dirección para la propiedad address predeterminada. Puedes 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[id]
String
Establece un valor de propiedad de dirección pasando la identificación de la propiedad, por ejemplo 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[name]
String
Establece la dirección para la propiedad 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
String
Establece la dirección de correo electrónico para la propiedad 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[id]
String
Establece un valor de propiedad de e-mail pasando la identificación de la propiedad, por ejemplo 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[name]
String
Establece la dirección de correo electrónico para la propiedad 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.
first_name
String
Nombre del cliente representado en el perfil.
last_name
String
Apellido del cliente representado en el perfil.
lists
array
Una colección de nombres de lista a la que se agregará este perfil. Pasar una colección vacía [] eliminará el perfil de todas las listas.
new_address
hash
Nueva dirección predeterminada del perfil. Si está presente, reemplazará la dirección predeterminada y se convertirá en la nueva predeterminada. Sin eliminar la antigua dirección predeterminada.
new_email
String
Nuevo e-mail por defecto del perfil. Si está presente, reemplaza el e-mail por defecto y será el nuevo e-mail por defecto del perfil. Sin eliminar el viejo e-mail por defecto.
new_phone
String
Nuevo teléfono por defecto del perfil. Si está presente, reemplaza el teléfono por defecto y será el nuevo teléfono por defecto del perfil. Sin eliminar el viejo teléfono por defecto.
phone
String
Establece el número de teléfono para la propiedad 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[id]
String
Establece un valor de propiedad de teléfono pasando la identificación de la propiedad, por ejemplo phone[gVlpOkwJ]=099888888. Pasar un valor vacío elimina el teléfono del perfil. Por ejemplo, phone[gVlpOkwJ]='' eliminará el teléfono del perfil.
phone[name]
String
Establece el número de teléfono para la propiedad 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[name]
String
Establece un valor de propiedad pasando el nombre de la propiedad, por ejemplo 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_by_id[id]
String
Establece un valor de propiedad pasando el id de la propiedad, por ejemplo, property[gVlpOkwJ]=MiValor. 
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.

Parámetros
email
String
Limita el resultado a los perfiles que tienen el e-mail especificado.
ending_before
String
Mostrar resultados listados antes (más recientes) que el id dado.
first_name
String
Limita los resultados a los perfiles que tienen el nombre especificado
last_name
String
Limita los resultados a los perfiles que tienen el apellido especificado
limit
integer
Limitar cuántos resultados mostrar. El valor por defecto es 25. El máximo es 100.
order
Enum
El orden para clasificar los perfiles. Si se especifica un valor no válido, se utiliza el orden predeterminado.
Valores enum posibles
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.

phone
String
Limita el resultado a los perfiles que tienen el teléfono especificado.
property[name]
String
Limita los resultados a los perfiles que tienen el valor de propiedad especificado.
starting_after
String
Mostrar resultados listados después (más antiguos) que el id dado. 
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ífica. Para más información, revisa el detalle de cada formato a continuación.

Una vez creadas, las nuevas propiedades están disponibles de inmediato en todos los perfiles nuevos y existentes.

Las propiedades phone, email, mercadolibre están agrupadas juntas y mostradas antes de todas las otras propiedades, 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

Atributos
id
String
Identificador único del objeto.
type
Type
Tipo de objeto. Esto es siempre property.
created_at
Epoch
Fecha de creación del objeto.
name
String
Nombre opcional de la propiedad.
position
integer
Posición numérica de la propiedad en relación a otras para establecer el orden.
profile
profile
Id del perfil al que pertenece esta propiedad.
unique
Boolean
¿Es la propiedad única o no? Por defecto es 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.
No se puede configurar como único.
birthday
checkbox
date
time
long_text
gender
list
tags
money 
{
  "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. Consulta la descripción de cada uno a continuación.

Los valores de las propiedades siempre se establecen desde el objeto de perfil.

La propiedad address

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.

Atributos
id
String
Identificador del objeto propiedad.
kind
String
El formato de la propiedad, siempre es address.
value
hash
Un objeto que contiene la información de la dirección. Mostrar atributos 
{
  "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

La propiedad birthday se basa en la propiedad date y hereda su estructura. Tiene un nombre diferente ya que está diseñada 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.

Atributos
id
String
Identificador único del objeto.
kind
String
El formato de la propiedad, esto es siempre birthday.
value
hash
Este hash representa una fecha. Es posible completar parcialmente con la información disponible. Por ejemplo, solo se puede ingresar el año de nacimiento o el día y el mes. Mostrar atributos 
{
  "id": "MQNKalb7",
  "kind": "birthday",
  "name": null,
  "value": {
    "day": 3,
    "month": 11,
    "year": 1985
  }
}

La propiedad checkbox

Atributos
id
String
Identificador único del objeto.
kind
String
El formato de la propiedad, siempre es checkbox.
value
Boolean
Espera true o false. Por defecto es false. 
{
  "id": "MQNKalb7",
  "kind": "checkbox",
  "name": null,
  "value": false
}

La propiedad company

Atributos
id
String
Identificador único del objeto.
kind
String
El formato de la propiedad, esto siempre es company.
value
String
Representa el nombre de una empresa. Puede ser utilizado para almacenar el nombre de la empresa con la que está asociado el perfil. 
{
  "id": "MQNKalb7",
  "kind": "company",
  "name": null,
  "value": "ACME Corporation"
}

La propiedad date

Atributos
id
String
Identificador único del objeto.
kind
String
El formato de la propiedad, esto es siempre date.
value
hash
Este hash representa una fecha. Es posible completar parcialmente con la información disponible. Por ejemplo, solo se puede ingresar el año de nacimiento o el día y el mes. Mostrar atributos 
{
  "id": "MQNKalb7",
  "kind": "date",
  "name": null,
  "value": {
    "day": 3,
    "month": 11,
    "year": 1985
  }
}

La propiedad time

Atributos
id
String
Identificador único del objeto.
kind
String
El formato de la propiedad, esto es siempre time.
value
hash
Este hash representa una hora. Es posible completar parcialmente con la información disponible. Por ejemplo, solo se puede ingresar la hora y el minuto. Mostrar atributos 
{
  "id": "MQNKalb7",
  "kind": "time",
  "name": null,
  "value": {
    "day": 3,
    "month": 11,
    "year": 1985,
    "hour": 10,
    "minute": 10,
    "second": 10
  }
}

La propiedad email

Atributos
id
String
Identificador único del objeto.
kind
String
El formato de la propiedad, esto siempre es email.
value
String
Representa una dirección de correo electrónico. Puede ser utilizado para almacenar la dirección de correo electrónico del perfil. 
{
  "id": "MQNKalb7",
  "kind": "email",
  "name": null,
  "value": "will.e@acme.com",
  "verified": true
}

La propiedad gender

Atributos
id
String
Identificador único del objeto.
kind
String
El formato de la propiedad, esto siempre es gender.
value
String
Valor que representa el género del perfil. Utiliza masculino para hombre y femenino para mujer. Utiliza cualquier otro valor para representar otros géneros. 
{
  "id": "MQNKalb7",
  "kind": "gender",
  "name": null,
  "value": "male"
}

La propiedad mercadolibre

Atributos
id
String
Identificador único del objeto.
kind
String
The format of the property, this is always mercadolibre.
value
String
Represents the username of a MercadoLibre user. 
{
  "id": "MQNKalb7",
  "kind": "mercadolibre",
  "name": null,
  "value": "WILLE900001"
}

Title

Atributos
id
String
Identificador único del objeto.
kind
String
El formato de la propiedad, esto siempre es money.
value
String
Este hash representa una cantidad de dinero. 
{
  "id": "MQNKalb7",
  "kind": "money",
  "name": null,
  "value": {
    "amount": 100,
    "currency": "USD"
  }
}

La propiedad number

Atributos
id
String
Identificador único del objeto.
kind
String
El formato de la propiedad, esto siempre es number.
value
float
Representa un número. Puede ser utilizado para almacenar cualquier valor numérico. 
{
  "id": "MQNKalb7",
  "kind": "number",
  "name": null,
  "value": 29.99
}

La propiedad phone

Atributos
id
String
Identificador único del objeto.
kind
String
El formato de la propiedad, esto siempre es phone.
value
String
Representa un número de teléfono. Puede ser utilizado para almacenar el número de teléfono del perfil. 
{
  "id": "MQNKalb7",
  "kind": "phone",
  "name": null,
  "value": "+59898000001",
  "verified": true
}

La propiedad tags

Atributos
id
String
Identificador único del objeto.
kind
String
El formato de la propiedad. Siempre es tags.
value
array
Representa una colección de etiquetas. 
{
  "id": "MQNKalb7",
  "kind": "tags",
  "name": null,
  "value": [
    "tag1",
    "tag2"
  ]
}

La propiedad text

Atributos
id
String
Identificador único del objeto.
kind
String
El formato de la propiedad, esto siempre es text.
value
String
Representa cualquier texto especificado. Puede ser utilizado para notas sobre el perfil o para almacenar cualquier metadato específico del negocio 
{
  "id": "MQNKalb7",
  "kind": "text",
  "name": null,
  "value": "Long lasting customer"
}

La propiedad url

Atributos
id
String
Identificador único del objeto.
kind
String
El formato de la propiedad, esto siempre es url.
value
String
Representa una URL. Puede ser utilizado para almacenar un enlace a un sitio web o cualquier otro recurso web. 
{
  "id": "MQNKalb7",
  "kind": "url",
  "name": null,
  "value": "https://www.hellotext.com"
}

Crear una propiedad

Crea una nueva propiedad.

Parámetros
kind
Enum
Requerido
El formato de la propiedad.
Valores enum posibles
address
email
phone
checkbox
date
number
tags
text
url
name
String
El nombre de la propiedad. Se aplican ciertas restricciones al nombre de la propiedad cuando se establece:
  • - El nombre no puede estar duplicado.
  • - El nombre no puede comenzar con un número. Por ejemplo, 1er-nombre es inválido.
  • - El nombre no puede contener llaves. Por ejemplo, {nombre} es inválido.
position
integer
Las nuevas propiedades obtienen el último número de posición si no se especifica. Si se da una posición diferente, las propiedades existentes actualizarán sus posiciones para establecer el nuevo orden. Los valores aceptados deben ser mayores que cero.
profile
profile
Id del perfil al que pertenece esta propiedad. Si se especifica, la propiedad solo estará disponible para el perfil especificado y no será visible para otros. Solo se puede asignar a address, email o phone. Requerido al crear propiedades de tipo address, email o phone.
unique
Boolean
¿Es la propiedad única o no? Por defecto es 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.

Parámetros
name
String
El nombre de la propiedad. Se aplican ciertas restricciones al nombre de la propiedad cuando se establece:
  • - El nombre no puede estar duplicado.
  • - El nombre no puede comenzar con un número. Por ejemplo, 1er-nombre es inválido.
  • - El nombre no puede contener llaves. Por ejemplo, {nombre} es inválido.
position
integer
Las nuevas propiedades obtienen el último número de posición si no se especifica. Si se da una posición diferente, las propiedades existentes actualizarán sus posiciones para establecer el nuevo orden. Los valores aceptados deben ser mayores que cero. Proporcionar un valor vacío position='' mueve la propiedad al final de la lista de propiedades.
unique
Boolean
Cambia la singularidad de la propiedad. Convertir una propiedad no única en única fallará si varios perfiles tienen el mismo valor. En estos casos, debes resolver el conflicto antes de continuar para hacer que la propiedad sea única. 
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.

Parámetros
ending_before
String
Mostrar resultados listados antes (más recientes) que el id dado.
limit
integer
Limitar cuántos resultados mostrar. El valor por defecto es 25. El máximo es 100.
profile
profile
Identificador único del perfil.
starting_after
String
Mostrar resultados listados después (más antiguos) que el id dado. 
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 objeto de la lista

Atributos
id
String
Identificador único del objeto.
type
Type
Tipo de objeto. Esto es siempre list.
created_at
Epoch
Fecha de creación del objeto.
name
String
Nombre de la lista. 
{
  "id": "zN4Xx4Km",
  "type": "list",
  "name": "Greens",
  "created_at": 1665684173
}

Crear una lista

Crea una nueva lista

Parámetros
name
String
Requerido
Nombre de la lista, distingue mayúsculas y minúsculas. No se permiten nombres duplicados. 
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.

Parámetros
name
String
Requerido
Nombre de la lista, distingue mayúsculas y minúsculas. No se permiten nombres duplicados. 
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 ordenadas por las más recientes. Los parámetros de paginación están disponibles en listas.

Parámetros
ending_before
String
Mostrar resultados listados antes (más recientes) que el id dado.
limit
integer
Limitar cuántos resultados mostrar. El valor por defecto es 25. El máximo es 100.
search
String
Mostrar listas cuyo nombre empiece con el valor proporcionado
starting_after
String
Mostrar resultados listados después (más antiguos) que el id dado. 
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

  • PATCH

    v1/templates/:id/move

El objeto de plantilla

Atributos
id
String
Identificador único del objeto.
type
Type
Tipo de objeto. Esto es siempre template.
body
String
El cuerpo de la plantilla.
buttons
array
Los botones asociados con la plantilla. Se ordenan según el índice o el parámetro position que especificaste al crear o actualizar la plantilla. Mostrar atributos
category
Enum
La categoría de la plantilla.
Valores enum posibles
marketing
utility Defecto
created_at
Epoch
Fecha de creación del objeto.
footer
String
El pie de la plantilla.
header
hash
El componente de encabezado de la plantilla. Mostrar atributos
name
String
El nombre de la plantilla.
position
integer
The position of the template. Useful for ordering templates in the dashboard.
state
Enum
El estado de la plantilla.
Valores enum posibles
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.

archived
technology
Enum
La plataforma objetivo para la cual se ha diseñado la plantilla.
Valores enum posibles
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"
    }
  ],
  "category": "marketing",
  "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úrate de que el tamaño del archivo esté dentro de las limitaciones de la plataforma resaltadas a continuación.
Limitaciones de Adjuntos en WhatsApp
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
Limitaciones de Adjuntos en Instagram
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.

Cuando una plantilla se dirige a whatsapp, ya sea explícitamente mediante technology=whatsapp o implícitamente mediante technology=any (cuando la empresa ha integrado una cuenta de WhatsApp), el cuerpo de la plantilla no puede comenzar ni terminar con parámetros colgantes. Un parámetro colgante es una etiqueta que aparece al inicio o al final del cuerpo sin estar precedida o seguida de una palabra o signo de puntuación. Por ejemplo, Hola {name}, ¿cómo podemos ayudarte? es válido, pero {name}, ¿cómo podemos ayudarte? y ¿Cómo podemos ayudarte hoy {name}? no lo son. Al intentar crear o actualizar una plantilla con un parámetro colgante se devolverá un error invalid.

Etiquetas Propiedades

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 {}. 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."
}

Etiquetas Shortlink

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 de 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.

Hellotext acorta los botones de URL que habilitan el seguimiento de atribuciones para saber exactamente quién y cuántas veces se hizo clic en un botón de URL.

Las plantillas están limitadas a 2 botones URL.

Atributos
type
Type
Tipo de objeto. Esto es siempre url.
text
String
El texto a mostrar en el botón. Máximo 25 caracteres.
url
URL
La URL a cargar cuando se toca el botón. 
{
  "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.

Atributos
type
Type
Tipo de objeto. Esto es siempre phone.
phone
String
El número de teléfono a llamar cuando se toca el botón. Máximo 20 caracteres.
text
String
El texto a mostrar en el botón. Máximo 25 caracteres. 
{
  "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.

Atributos
type
Type
Tipo de objeto. Esto es siempre quick_reply.
text
String
El texto a mostrar en el botón. Máximo 25 caracteres. 
{
  "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.

Atributos
type
Type
Tipo de objeto. Esto es siempre copy.
copy
String
El texto a copiar al portapapeles cuando se toca el botón. Requerido cuando el tipo es copy. Máximo 15 caracteres.
text
String
El texto a mostrar en el botón. Máximo 25 caracteres. 
{
  "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 WhatsApp no pueden tener parámetros colgantes. Al intentar crear una plantilla de WhatsApp con un parámetro colgante se devolverá un error invalid.
  • Las plantillas de SMS están limitadas a 160 caracteres.
  • La plantilla de SMS no admite los componentes header, footer o buttons. Al intentar asignar estos componentes se devuelve un error invalid.
Parámetros
body
String
Requerido
El cuerpo de la plantilla. La longitud máxima es 1024 caracteres.
buttons
array
Los botones asociados a la plantilla. Máximo 10 botones en total. Consulta los tipos de botones para obtener más información.

Se selecciona una posición automática en función del índice del botón cuando no se especifica ninguna position. Puedes incluir un argumento opcional position entre 1 y 10 para indicar el orden del botón. Mostrar atributos
category
Enum
solo WhatsApp. Las plantillas de marketing se utilizan para promocionar productos y servicios, y están sujetas a estándares de calidad más estrictos por parte de WhatsApp y se cobran a un precio más alto. Una vez establecido, no se puede cambiar.
Valores enum posibles
marketing
utility Defecto
footer
String
El pie de la plantilla. Solo WhatsApp. Limitado a 60 caracteres, los emojis se eliminan automáticamente ya que WhatsApp prohíbe los emojis en los pies de plantilla.
header
hash
El componente de encabezado de la plantilla. Mostrar atributos
name
String
Requerido
El nombre de la plantilla. Sensible a mayúsculas, no se permiten nombres duplicados.
position
integer
Posición numérica de la plantilla en relación a otras para ordenar. Las plantillas nuevas se agregan al final de la lista por defecto. Puedes pasar un valor entero para mover la plantilla a una posición específica.
technology
Enum
La plataforma de destino prevista para la plantilla. WhatsApp solo se puede configurar cuando la empresa ha integrado una cuenta de WhatsApp. Si intentas crear una plantilla de WhatsApp sin haber integrado WhatsApp, se devolverá un error.

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.
Valores enum posibles
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"
    }
  ],
  "category": "marketing",
  "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"
    }
  ],
  "category": "marketing",
  "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 pending será rechazado con un error invalid.
  • Los nombres no se pueden cambiar. Si proporcionas name en los parámetros, se ignora.
Parámetros
body
String
El cuerpo de la plantilla. La longitud máxima es 1024 caracteres.
buttons
array
Los botones asociados con la plantilla. Se selecciona una posición automática basada en el índice del botón. Puedes pasar un array vacío [] para eliminar todos los botones de la plantilla. Mostrar atributos
footer
String
El pie de la plantilla. Solo WhatsApp. Limitado a 60 caracteres, los emojis se eliminan automáticamente ya que WhatsApp prohíbe los emojis en los pies de plantilla.
header
hash
El componente de encabezado de la plantilla. Puedes pasar null o {} para eliminar el encabezado. Si el tipo de encabezado era un adjunto, el adjunto se elimina de los servidores de Hellotext. Mostrar atributos
name
String
El nombre de la plantilla. No se permiten nombres duplicados que distingan entre mayúsculas y minúsculas. Si la plantilla está dirigida a WhatsApp, las actualizaciones del nombre se ignoran. Esto se debe a que los nombres de las plantillas de WhatsApp no se pueden cambiar una vez creados.
technology
Enum
La plataforma de destino prevista para la plantilla. Una vez cambiada, se vuelve inutilizable en la plataforma anterior. Por ejemplo, cambiar la tecnología de 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.
Valores enum posibles
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"
    }
  ],
  "category": "marketing",
  "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.

Parámetros
ending_before
String
Mostrar resultados listados antes (más recientes) que el id dado.
limit
integer
Limitar cuántos resultados mostrar. El valor por defecto es 25. El máximo es 100.
starting_after
String
Mostrar resultados listados después (más antiguos) que el id dado. 
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"
        }
      ],
      "category": "marketing",
      "created_at": 1665684173,
      "footer": "Send STOP to unsubscribe",
      "state": "approved",
      "header": {
        "type": "text",
        "text": "Welcome to our store"
      }
    },
    "{...}",
    "{...}"
  ]
}

Actualizar la posición de una plantilla

Actualiza la posición de un objeto de plantilla.

Las actualizaciones se propagan a las plantillas circundantes de acuerdo.

Parámetros
position
integer
Mueve la plantilla a una posición específica. La actualización se propaga y otras plantillas se actualizan de acuerdo. 
curl -X PATCH https://api.hellotext.com/v1/templates/:id/move 
 -d position=1 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "id": "xJEOaPdk",
  "position": 1
}

El Objeto de Mensaje

Un mensaje es una comunicación entre tú y un perfil. Puedes enviar mensajes de texto o reutilizar una Plantilla existente.

  • POST

    v1/messages

  • GET

    v1/messages/:id

  • GET

    v1/messages

El Objeto de Mensaje

Atributos
id
String
Identificador único del objeto.
type
Type
Tipo de objeto. Esto es siempre message.
attachments
array
Una lista de archivos adjuntos asociados con el mensaje.
body
String
The content of the message. Optional when using a template, required when no template is specified.
created_at
Epoch
Fecha de creación del objeto.
delivered_at
Epoch
La marca de tiempo de cuando el mensaje fue entregado.
destination
String
El identificador del perfil que recibirá el mensaje. Puede ser un número de teléfono, nombre de usuario de Instagram o ID de usuario de MercadoLibre.
failed_at
Epoch
La marca de tiempo de cuando el mensaje falló en ser entregado.
origin
String
El identificador del canal utilizado para enviar el mensaje.
profile
profile
El id del perfil al que se enviará el mensaje.
received_at
Epoch
La marca de tiempo de cuando el mensaje fue recibido por el perfil. Esto se puede usar para determinar si el mensaje fue del perfil o del negocio.
routed_at
Epoch
La marca de tiempo de cuando el mensaje fue dirigido a la pasarela externa.
state
Enum
El estado actual del mensaje.
Valores enum posibles
delivered

El mensaje ha sido entregado exitosamente. Consulta 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.

technology
Enum
La tecnología utilizada para entregar el mensaje.
Valores enum posibles
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.

template
template
El id de la plantilla utilizada para enviar el mensaje. 
{
  "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

Aprende cómo enviar mensajes usando una plantilla. Asegúrate 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

Puedes reservar un espacio para enlaces cortos dinámicos en el cuerpo de la plantilla cuando la creas. Consulta 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 has creado una plantilla con enlaces cortos dinámicos y tienes 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. Considera 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, proporciona 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 observas los Parámetros del Mensaje que tenemos al crear el mensaje, verás 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 pueden tener diferentes longitudes dependiendo del contenido del mensaje. El valor por defecto para GSM 7-bit es de 160 caracteres, Latin-1 es de 140 caracteres, y UCS-2 es de 70 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_state del 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úrate de que el tamaño del archivo esté dentro de las limitaciones de la plataforma resaltadas a continuación.
Limitaciones de Adjuntos en WhatsApp
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
Limitaciones de Adjuntos en Instagram
Tipo de Medio Formatos Compatibles Tamaño Máximo

Imagen

png, jpeg, gif

8MB

Video

mp4, ogg, avi, mov, webm

25MB
Parámetros
attachments
array
Una lista de URLs de archivos adjuntos para enviar con el mensaje. Asegúrate de que cada URL sea accesible públicamente, los archivos adjuntos se descargan y se almacenan en los servidores de Hellotext. Ten en cuenta que SMS no admite archivos adjuntos, por lo tanto, este parámetro se ignora para la tecnología sms.
body
String
Requerido
The content of the message. Optional when using a template, required when no template is specified.
destination
String
El identificador del destino del perfil al que enviar el mensaje. Puede ser un número de teléfono, nombre de usuario de Instagram o ID de usuario de MercadoLibre.

Hellotext selecciona automáticamente un destino basado en el origin y technology configurados. De lo contrario, puedes especificar el destino para enviar el mensaje a un identificador específico del perfil.

Cuando se envía mensajes a números de teléfono, es ideal proporcionar el número de teléfono en formato E.164, de lo contrario, Hellotext usará el código de país del negocio para formatear y sanitizar el número de teléfono.
origin
String
El identificador del canal utilizado para enviar el mensaje. Cuando esto está vacío, Hellotext determinará el mejor canal a utilizar según la accesibilidad del perfil y los canales configurados por el negocio.

Por ejemplo, al enviar un mensaje a un perfil, si no especificas 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.
profile
profile
Id del perfil. Cuando es nulo, Hellotext intentará encontrar un contacto existente por el destination y crear uno nuevo si no existe.
technology
Enum
La tecnología por la cual enrutar el mensaje. Cuando esto está vacío, Hellotext determinará la mejor tecnología a utilizar según la accesibilidad del perfil y los canales configurados por el negocio. Las tecnologías tienen el siguiente orden de prioridad: WhatsApp, Instagram y SMS.

Ten 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.
Valores enum posibles
instagram
sms
whatsapp
template
hash
Ya sea un identificador de cadena de la plantilla que se utilizará al enviar el mensaje o un hash. Cuando se establece, el cuerpo del mensaje se ignora y en su lugar se utiliza el cuerpo de la plantilla. Las plantillas son mensajes reutilizables que se pueden utilizar para enviar mensajes a perfiles. Cuando la plantilla tiene enlaces cortos dinámicos, debes proporcionar las URL de los enlaces cortos al crear el mensaje. Si no se proporciona una URL para un enlace corto dinámico, se devolverán errores. Mostrar atributos 
curl -X POST https://api.hellotext.com/v1/messages 
 -d origin="+14155552671" 
 -d profile="zGrDJ1Lb" 
 -d template="K75Vq1dL" 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "status": "received"
}
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..."
{
  "status": "received"
}

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..."
{
  "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
}

Listar Mensajes

Lista todos los mensajes enviados por la empresa.

Parámetros
ending_before
String
Mostrar resultados listados antes (más recientes) que el id dado.
limit
integer
Limitar cuántos resultados mostrar. El valor por defecto es 25. El máximo es 100.
starting_after
String
Mostrar resultados listados después (más antiguos) que el id dado. 
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

Atributos
id
String
Identificador único del objeto.
type
Type
Tipo de objeto. Esto es siempre coupon.
code
String
Código canjeable del cupón. Este es el nombre del cupón que ve el cliente, es decir, SALE.
created_at
Epoch
Fecha de creación del objeto.
description
String
Descripción del cupón. Disponible como una etiqueta para ser utilizada en los mensajes.
destination_url
URL
URL para canjear el cupón.
reference
String
El número de cupón o el identificador original de la fuente externa que creó el 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.

Parámetros
code
String
Requerido
Código canjeable del cupón. Este es el nombre del cupón que ve el cliente, es decir, SALE. Distingue mayúsculas y minúsculas. No se permiten códigos duplicados.
description
String
Requerido
Descripción del cupón. Disponible como una etiqueta para ser utilizada en los mensajes.
destination_url
URL
Requerido
URL para canjear el cupón.
reference
String
El número de cupón o el identificador original de la fuente externa que creó el cupón. 
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.

Parámetros
code
String
Requerido
Código canjeable del cupón. Este es el nombre del cupón que ve el cliente, es decir, SALE. Distingue mayúsculas y minúsculas. No se permiten códigos duplicados.
description
String
Requerido
Descripción del cupón. Disponible como una etiqueta para ser utilizada en los mensajes.
destination_url
URL
Requerido
URL para canjear el cupón.
reference
String
El número de cupón o el identificador original de la fuente externa que creó el cupón. 
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.

Parámetros
ending_before
String
Mostrar resultados listados antes (más recientes) que el id dado.
limit
integer
Limitar cuántos resultados mostrar. El valor por defecto es 25. El máximo es 100.
starting_after
String
Mostrar resultados listados después (más antiguos) que el id dado. 
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 tu 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úrate 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 pases 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

Rastrea eventos importantes realizados por tus clientes cuando interactúan con tu aplicación. Las acciones más comunes incluyen rastrear cuando una aplicación se instala con la acción app.installed, se elimina con app.removed, o cuando un usuario gasta una cierta cantidad con app.spent.

Cuando se rastrean eventos asociados a sesiones creadas después de una campaña, todos los valores de atribución, incluidos los valores monetarios, se agregarán en los informes de la campaña.

Parámetros
action
Enum
Requerido
El nombre de la acción a rastrear.
Valores enum posibles
app.installed
app.removed
app.spent
amount
float
Monto monetario que representa los ingresos asociados a este evento rastreado. El valor predeterminado es null.
currency
String
Moneda del amount proporcionada en formato ISO 4217. Si no se especifica, la moneda se deducirá de la moneda predeterminada de la empresa.
object
String
ID de un objeto de aplicación existente.
object_parameters
hash
Parámetros para crear un nuevo objeto de aplicación. Consulta los parámetros disponibles en la sección Crear una aplicación para obtener más información sobre los parámetros que puedes pasar.

Si existe una aplicación con el mismo name, se usará la aplicación existente en lugar de crear una aplicación duplicada.
profile
String
Requerido si la sesión no está especificada. Identificador único del objeto de perfil al que pertenece este evento. Si no se especifica explícitamente, el identificador del perfil puede heredarse cuando se especifica el parámetro de sesión y la sesión ya está asociada a un perfil o se adjunta a uno más adelante.
session
String
Requerido si el perfil no está especificado. Identificador del objeto de sesión al que pertenece este evento. Las sesiones son identificadores generados automáticamente a partir de clics de visitantes en enlaces cortos o desde la biblioteca Hellotext.js al rastrear visitantes anónimos. Es una forma de rastrear eventos en el lado del cliente sin autenticar ni divulgar el identificador del perfil, permitiendo asociarlo posteriormente de manera segura a un perfil en el servidor.
tracked_at
Epoch
Fecha original en la que ocurrió el evento. Esto es útil si deseas registrar un evento que ocurrió en el pasado. Si no se proporciona un valor, su valor será el mismo que el de created_at.
url
URL
URL de la página donde ocurrió el evento. Si no se especifica, la URL se inferirá de la página actual. 
curl -X POST https://api.hellotext.com/v1/attribution/events 
 -d action="app.installed" 
 -d app="Jp10Kwog" 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
curl -X POST https://api.hellotext.com/v1/attribution/events 
 -d action="app.installed" 
 -d app_parameters[name]="My Amazing App" 
 -d app_parameters[image_url]="https//example.com/image.jpg" 
 -d app_parameters[property][custom property]="custom value" 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "status": "received"
}

Eventos de carrito

Rastrea los eventos realizados por tus clientes cuando agregan o eliminan artículos de su carrito de compras o abandonan el carrito.

Los valores monetarios asociados a los eventos del carrito se agregarán a los informes de la campaña.

Parámetros
action
Enum
Requerido
El nombre de la acción a rastrear.
Valores enum posibles
cart.abandoned
amount
float
Monto monetario que representa los ingresos asociados a este evento rastreado. El valor predeterminado es 0.
currency
String
Moneda del amount proporcionada en formato ISO 4217. Si no se especifica, la moneda se deducirá de la moneda predeterminada de la empresa.
object
String
Un ID de un objeto de carrito existente.
object_parameters
hash
Parámetros para crear un nuevo objeto de carrito. Consulta los parámetros disponibles en la sección Crear un carrito para obtener más información sobre los parámetros que puedes pasar.

Si existe un carrito con el mismo reference, se usará el carrito existente en lugar de crear un carrito duplicado.
profile
String
Requerido si la sesión no está especificada. Identificador único del objeto de perfil al que pertenece este evento. Si no se especifica explícitamente, el identificador del perfil puede heredarse cuando se especifica el parámetro de sesión y la sesión ya está asociada a un perfil o se adjunta a uno más adelante.
session
String
Requerido si el perfil no está especificado. Identificador del objeto de sesión al que pertenece este evento. Las sesiones son identificadores generados automáticamente a partir de clics de visitantes en enlaces cortos o desde la biblioteca Hellotext.js al rastrear visitantes anónimos. Es una forma de rastrear eventos en el lado del cliente sin autenticar ni divulgar el identificador del perfil, permitiendo asociarlo posteriormente de manera segura a un perfil en el servidor.
tracked_at
Epoch
Fecha original en la que ocurrió el evento. Esto es útil si deseas registrar un evento que ocurrió en el pasado. Si no se proporciona un valor, su valor será el mismo que el de created_at.
url
URL
URL de la página donde ocurrió el evento. Si no se especifica, la URL se inferirá de la página actual. 
curl -X POST https://api.hellotext.com/v1/attribution/events 
 -d action="refund.requested" 
 -d object="Jp10Kwog" 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
curl -X POST https://api.hellotext.com/v1/attribution/events 
 -d action="refund.requested" 
 -d object_parameters[order]="Jp10Kwog" 
 -d object_parameters[reference]="123456" 
 -d object_parameters[source]=shopify 
 -d object_parameters[property][custom property]="custom value" 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "status": "received"
}

Eventos de cupones

Rastrea eventos relacionados con el uso de cupones por parte de tus clientes. Las acciones más comunes incluyen rastrear cuando un cupón se canjea con la acción coupon.redeemed, se crea con coupon.created o se elimina con coupon.deleted.

Los valores monetarios asociados a los cupones se agregarán a los informes de la campaña.

Parámetros
action
Enum
Requerido
El nombre de la acción a rastrear.
Valores enum posibles
coupon.redeemed
amount
float
Monto monetario que representa los ingresos asociados a este evento rastreado. El valor predeterminado es 0.
currency
String
Moneda del amount proporcionada en formato ISO 4217. Si no se especifica, la moneda se deducirá de la moneda predeterminada de la empresa.
object
String
Un ID de un objeto de cupón existente.
object_parameters
hash
Parámetros para crear un nuevo objeto de cupón. Consulta los parámetros disponibles en la sección Crear un cupón para obtener más información sobre los parámetros que puedes pasar.

Si existe un cupón con el mismo code, se usará el cupón existente en lugar de crear un cupón duplicado.
profile
String
Requerido si la sesión no está especificada. Identificador único del objeto de perfil al que pertenece este evento. Si no se especifica explícitamente, el identificador del perfil puede heredarse cuando se especifica el parámetro de sesión y la sesión ya está asociada a un perfil o se adjunta a uno más adelante.
session
String
Requerido si el perfil no está especificado. Identificador del objeto de sesión al que pertenece este evento. Las sesiones son identificadores generados automáticamente a partir de clics de visitantes en enlaces cortos o desde la biblioteca Hellotext.js al rastrear visitantes anónimos. Es una forma de rastrear eventos en el lado del cliente sin autenticar ni divulgar el identificador del perfil, permitiendo asociarlo posteriormente de manera segura a un perfil en el servidor.
tracked_at
Epoch
Fecha original en la que ocurrió el evento. Esto es útil si deseas registrar un evento que ocurrió en el pasado. Si no se proporciona un valor, su valor será el mismo que el de created_at.
url
URL
URL de la página donde ocurrió el evento. Si no se especifica, la URL se inferirá de la página actual. 
curl -X POST https://api.hellotext.com/v1/attribution/events 
 -d action="coupon.redeemed" 
 -d object="Jp10Kwog" 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
curl -X POST https://api.hellotext.com/v1/attribution/events 
 -d action="coupon.redeemed" 
 -d object_parameters[code]="20OFF" 
 -d object_parameters[destination_url]="https://www.example.com" 
 -d object_parameters[description]="20% off your next purchase" 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "status": "received"
}

Eventos de formularios

Rastrea los eventos realizados por tus clientes cuando completan un formulario. Las acciones disponibles son form.completed.

Los valores monetarios asociados a los eventos del formulario se agregarán a los informes de la campaña.

Asegúrate de haber leído y entendido los Objetos antes de continuar.

Aprende más sobre Objetos.

Parámetros
action
Enum
Requerido
El nombre de la acción a rastrear.
Valores enum posibles
form.completed
currency
String
Moneda del amount proporcionada en formato ISO 4217. Si no se especifica, la moneda se deducirá de la moneda predeterminada de la empresa.
form
String
Un ID del objeto de formulario completado.
metadata
Hash
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
object_parameters
hash
Parámetros que se establecerán para el objeto. Mostrar atributos
profile
String
Identificador único del objeto de perfil al que pertenece este evento.
session
String
Identificador del objeto de sesión al que pertenece este evento.
tracked_at
Epoch
Fecha original en la que ocurrió el evento. Esto es útil si deseas registrar un evento que ocurrió en el pasado. Si no se proporciona ningún valor, su valor será el mismo que el de created_at.
url
URL
URL de la página donde ocurrió el evento. 
curl -X POST https://api.hellotext.com/v1/attribution/events 
 -d action="form.completed" 
 -d form="zGrDJ1Lb" 
 -d form_parameters[property_by_id][zGrDJ1Lb]="value for an existing property within the Form object" 
 -d form_parameters[property][Dynamic property]="Value for a dynamic property that is not part of the Form object" 
 -d form_parameters[property][phone]="+12345678" 
 -d form_parameters[property][email]="will@acme.com" 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "status": "received"
}

Eventos de órdenes

Rastrea los eventos relacionados con el ciclo de vida de las órdenes de tus clientes. Las acciones disponibles son order.placed cuando un cliente realiza un pedido, order.confirmed cuando se confirma, order.cancelled si se cancela y order.shipped cuando se envía.

Los valores monetarios asociados a las órdenes se agregarán a los informes de la campaña.

Parámetros
action
Enum
Requerido
El nombre de la acción personalizada a rastrear. La acción personalizada debe haber sido creada previamente.
Valores enum posibles
order.printed_label
order.confirmed
order.cancelled
order.delivered
checkout.started
order.placed
order.shipped
amount
float
Monto monetario que representa los ingresos asociados a este evento rastreado. El valor predeterminado es null.
currency
String
Moneda del amount proporcionada en formato ISO 4217. Si no se especifica, la moneda se deducirá de la moneda predeterminada de la empresa.
object
String
ID de un objeto de orden existente.
object_parameters
hash
Parámetros para crear una nueva orden. Consulta los parámetros disponibles en la sección Crear una orden para obtener más información sobre los parámetros que puedes pasar.

Si existe una orden con la misma reference, se usará la orden existente en lugar de crear una orden duplicada.
profile
String
Requerido si la sesión no está especificada. Identificador único del objeto de perfil al que pertenece este evento. Si no se especifica explícitamente, el identificador del perfil puede heredarse cuando se especifica el parámetro de sesión y la sesión ya está asociada a un perfil o se adjunta a uno más adelante.
session
String
Requerido si el perfil no está especificado. Identificador del objeto de sesión al que pertenece este evento. Las sesiones son identificadores generados automáticamente a partir de clics de visitantes en enlaces cortos o desde la biblioteca Hellotext.js al rastrear visitantes anónimos. Es una forma de rastrear eventos en el lado del cliente sin autenticar ni divulgar el identificador del perfil, permitiendo asociarlo posteriormente de manera segura a un perfil en el servidor.
tracked_at
Epoch
Fecha original en la que ocurrió el evento. Esto es útil si deseas registrar un evento que ocurrió en el pasado. Si no se proporciona un valor, su valor será el mismo que el de created_at.
url
URL
URL de la página donde ocurrió el evento. Si no se especifica, la URL se inferirá de la página actual. 
curl -X POST https://api.hellotext.com/v1/attribution/events 
 -d action="order.confirmed" 
 -d object="Jp10Kwog" 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
curl -X POST https://api.hellotext.com/v1/attribution/events 
 -d action="order.confirmed" 
 -d object_parameters[reference]="Jp10Kwog" 
 -d object_parameters[delivery]="deliver" 
 -d object_parameters[items][][product]="vxqQJ3Yg" 
 -d object_parameters[items][][quantity]=1 
 -d object_parameters[property][custom property]="custom value" 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "status": "received"
}

Eventos de productos

Rastrea los eventos de compras realizadas por tus clientes. Si tus clientes realizan pedidos, en su lugar puedes rastrear las acciones del pedido. Las acciones disponibles para productos son product.purchased cuando un cliente compra un producto y product.viewed cuando un producto es visto desde una página de producto.

Los valores monetarios asociados a la compra del producto se agregarán a los informes de la campaña.

Este endpoint se puede utilizar con Productos y Variantes de Producto. Si deseas rastrear un Producto o una Variante de Producto existente, asegúrate de pasar el id, reference o sku de un registro existente. Si deseas crear un nuevo Producto, debes pasar el parámetro object_parameters.

Parámetros
action
Enum
Requerido
El nombre de la acción a rastrear.
Valores enum posibles
product.added_to_wishlist
product.browse_abandoned
product.price_changed
product.removed_from_wishlist
product.restocked
product.viewed
product.went_out_of_stock
product.purchased
amount
float
Monto monetario que representa los ingresos asociados a este evento rastreado. El valor predeterminado es 0.
currency
String
Moneda del amount proporcionada en formato ISO 4217. Si no se especifica, la moneda se deducirá de la moneda predeterminada de la empresa.
object
String
ID de un producto existente o de un objeto de variante de producto.
object_parameters
hash
Parámetros para crear un nuevo producto o una variante de producto. Consulta los parámetros disponibles en la sección Creación de un producto o Creación de una variante de producto para más información sobre los parámetros que puedes pasar.

Si se encuentra un producto o una variante de producto existente con el mismo reference o sku, se usará el producto o variante existente en lugar de crear un duplicado.
profile
String
Requerido si la sesión no está especificada. Identificador único del objeto de perfil al que pertenece este evento. Si no se especifica explícitamente, el identificador del perfil puede heredarse cuando se especifica el parámetro de sesión y la sesión ya está asociada a un perfil o se adjunta a uno más adelante.
session
String
Requerido si el perfil no está especificado. Identificador del objeto de sesión al que pertenece este evento. Las sesiones son identificadores generados automáticamente a partir de clics de visitantes en enlaces cortos o desde la biblioteca Hellotext.js al rastrear visitantes anónimos. Es una forma de rastrear eventos en el lado del cliente sin autenticar ni divulgar el identificador del perfil, permitiendo asociarlo posteriormente de manera segura a un perfil en el servidor.
tracked_at
Epoch
Fecha original en la que ocurrió el evento. Esto es útil si deseas registrar un evento que ocurrió en el pasado. Si no se proporciona un valor, su valor será el mismo que el de created_at.
url
URL
URL de la página donde ocurrió el evento. Si no se especifica, la URL se inferirá de la página actual. 
curl -X POST https://api.hellotext.com/v1/attribution/events 
 -d action="product.viewed" 
 -d object="Jp10Kwog" 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
curl -X POST https://api.hellotext.com/v1/attribution/events 
 -d action="product.viewed" 
 -d object_parameters[name]="Yeezy Boost 350 V2" 
 -d object_parameters[image_url]="https//example.com/image.jpg" 
 -d object_parameters[reference]="Jp10Kwog" 
 -d object_parameters[source]=shopify 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "status": "received"
}

Eventos de variantes de productos

Rastrea los eventos de compras realizadas por tus clientes. Si tus clientes realizan pedidos, en su lugar puedes rastrear las acciones del pedido. Las acciones disponibles para productos son product.purchased cuando un cliente compra un producto y product.viewed cuando un producto es visto desde una página de producto.

Los valores monetarios asociados a la compra del producto se agregarán a los informes de la campaña.

Parámetros
action
Enum
Requerido
El nombre de la acción a rastrear.
Valores enum posibles
product.added_to_wishlist
product.browse_abandoned
product.price_changed
product.removed_from_wishlist
product.restocked
product.viewed
product.went_out_of_stock
product.purchased
amount
float
Monto monetario que representa los ingresos asociados a este evento rastreado. El valor predeterminado es 0.
currency
String
Moneda para el amount en formato ISO 4217. Si no se especifica, la moneda se inferirá de la moneda predeterminada del negocio.
object
String
ID de un objeto de variante de producto existente. Requerido cuando object_parameters está vacío.
object_parameters
hash
Parámetros para crear un nuevo objeto de variante de producto. Requerido cuando object está vacío.

Consulta los parámetros disponibles en la sección Creación de una variante de producto para más información sobre los parámetros que puedes pasar.

Si se encuentra una variante de producto existente con el mismo reference o sku, se usará la variante existente en lugar de crear un duplicado. Mostrar atributos
profile
String
Requerido si no se especifica la sesión. Identificador único del objeto de perfil al que pertenece este evento. Si no se especifica explícitamente, el identificador de perfil puede heredarse cuando se especifica el parámetro de sesión y la sesión ya está asociada a un perfil o se asocia más adelante.
session
String
Requerido si no se especifica el perfil. Identificador del objeto de sesión al que pertenece este evento. Las sesiones son identificadores generados automáticamente a partir de clics de visitantes en enlaces cortos o desde la biblioteca Hellotext.js cuando se realiza un seguimiento de visitantes anónimos. Es una forma de rastrear eventos del lado del cliente sin autenticar ni divulgar el identificador del perfil, permitiendo asociarlo de manera segura a un perfil en el servidor más adelante.
tracked_at
Epoch
Fecha original en la que ocurrió el evento. Esto es útil si deseas registrar un evento que ocurrió en el pasado. Si no se proporciona un valor, tomará el mismo valor que created_at.
url
URL
URL de la página donde ocurrió el evento. Si no se especifica, la URL se inferirá de la página actual. 
curl -X POST https://api.hellotext.com/v1/attribution/events 
 -d action="product.viewed" 
 -d object="Jp10Kwog" 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
curl -X POST https://api.hellotext.com/v1/attribution/events 
 -d action="product.viewed" 
 -d object_parameters[name]="Yeezy Boost 350 V2 in Red" 
 -d object_parameters[image_url]="https//example.com/image.jpg" 
 -d object_parameters[reference]="Jp10Kwog" 
 -d object_parameters[source]=shopify 
 -d object_parameters[product]="vxqQJ3YQ" 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
curl -X POST https://api.hellotext.com/v1/attribution/events 
 -d action="product.viewed" 
 -d object_parameters[name]="Yeezy Boost 350 V2 in Red" 
 -d object_parameters[image_url]="https//example.com/image.jpg" 
 -d object_parameters[reference]="Jp10Kwog" 
 -d object_parameters[source]=shopify 
 -d object_parameters[product_parameters][name]="Yeezy Boost 350 V2" 
 -d object_parameters[product_parameters][sku]="1234567890" 
 -d object_parameters[product_parameters][reference]="YEEZYBOOST350V2" 
 -d object_parameters[product_parameters][source]=shopify 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "status": "received"
}

Eventos de reembolsos

Rastrea eventos relacionados con los reembolsos de tus clientes. Las acciones más comunes incluyen rastrear cuando un reembolso se procesa con la acción refund.processed, se rechaza con refund.rejected o se cancela con refund.cancelled.

Los valores monetarios asociados a los reembolsos se restarán de los informes de la campaña.

Parámetros
action
Enum
Requerido
El nombre de la acción a rastrear.
Valores enum posibles
refund.requested
refund.received
amount
float
Monto monetario que representa los ingresos asociados a este evento rastreado. El valor predeterminado es 0.
currency
String
Moneda del amount proporcionada en formato ISO 4217. Si no se especifica, la moneda se deducirá de la moneda predeterminada de la empresa.
object
String
Un ID de un objeto de reembolso existente.
object_parameters
hash
Parámetros para crear un nuevo objeto de reembolso. Consulta los parámetros disponibles en la sección Crear un reembolso para obtener más información sobre los parámetros que puedes pasar.

Si existe un reembolso con el mismo reference, se usará el reembolso existente en lugar de crear un reembolso duplicado.
profile
String
Requerido si la sesión no está especificada. Identificador único del objeto de perfil al que pertenece este evento. Si no se especifica explícitamente, el identificador del perfil puede heredarse cuando se especifica el parámetro de sesión y la sesión ya está asociada a un perfil o se adjunta a uno más adelante.
session
String
Requerido si el perfil no está especificado. Identificador del objeto de sesión al que pertenece este evento. Las sesiones son identificadores generados automáticamente a partir de clics de visitantes en enlaces cortos o desde la biblioteca Hellotext.js al rastrear visitantes anónimos. Es una forma de rastrear eventos en el lado del cliente sin autenticar ni divulgar el identificador del perfil, permitiendo asociarlo posteriormente de manera segura a un perfil en el servidor.
tracked_at
Epoch
Fecha original en la que ocurrió el evento. Esto es útil si deseas registrar un evento que ocurrió en el pasado. Si no se proporciona un valor, su valor será el mismo que el de created_at.
url
URL
URL de la página donde ocurrió el evento. Si no se especifica, la URL se inferirá de la página actual. 
curl -X POST https://api.hellotext.com/v1/attribution/events 
 -d action="refund.requested" 
 -d object="Jp10Kwog" 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
curl -X POST https://api.hellotext.com/v1/attribution/events 
 -d action="refund.requested" 
 -d object_parameters[order]="Jp10Kwog" 
 -d object_parameters[reference]="123456" 
 -d object_parameters[source]=shopify 
 -d object_parameters[property][custom property]="custom value" 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "status": "received"
}

Rastrear eventos personalizados

Hellotext proporciona una lista de acciones listas para usar para rastrear las interacciones más comunes de los clientes con tu negocio, como compras, visitas a tu sitio, productos agregados al carrito, completar formularios y más. Sin embargo, estas no siempre son suficientes y a veces necesitas un poco más de flexibilidad al definir acciones específicas para tus necesidades comerciales.

Es posible especificar cualquier nombre de acción personalizada al rastrear eventos siempre que el objeto de acción haya sido creado previamente. Una vez que se crea la acción, simplemente puedes usar su nombre para rastrear un nuevo evento.

Ten en cuenta que los valores monetarios pasados a estos eventos se agregarán a los informes de campaña como ventas si la acción está marcada como una conversión.

Se puede rastrear un evento personalizado sin ninguna asociación a un objeto en particular. Si deseas rastrear un evento sin asociarlo a ningún objeto, omite object, object_parameters y object_type.

Más sobre Acciones.

Parámetros
action
String
Requerido
El nombre de la acción personalizada a rastrear. La acción personalizada debe haber sido creada previamente.
amount
float
Cantidad monetaria que representa los ingresos asociados a este evento rastreado. El valor predeterminado es null.
currency
String
Moneda del amount proporcionada en formato ISO 4217. Si no se especifica, la moneda se deducirá de la moneda predeterminada de la empresa.
object
String
Un ID de un objeto personalizado existente. El objeto personalizado debe haber sido creado previamente.

Aprende más sobre Objetos.
object_parameters
hash
Un hash de parámetros del objeto. El objeto se crea con los parámetros especificados y se asociará con el evento.

Los parámetros deben ser válidos y estar presentes dentro del objeto personalizado. Por ejemplo, si has creado un objeto llamado Cita con las propiedades Reservado En y Habitación, debes especificar los parámetros como object_parameters[Booked At]=2021-01-01T12:00:00Z y object_parameters[room]=101. Los nombres de los parámetros no distinguen entre mayúsculas y minúsculas. Por lo tanto, appointment_parameters[booked at] también es válido.

Aprende más sobre Objetos.
object_type
String
Requerido
Un ID o el tipo de objeto a crear. Esto corresponde al ID o al nombre del objeto que estableciste al crearlo.

Aprende más sobre Objetos.
profile
String
Requerido si la sesión no está especificada. Identificador único del objeto de perfil al que pertenece este evento. Si no se especifica explícitamente, el identificador de perfil puede heredarse cuando se especifica el parámetro de sesión y la sesión ya está asociada a un perfil o se adjunta más tarde.
session
String
Requerido si el perfil no está especificado. Identificador del objeto de sesión al que pertenece este evento. Las sesiones son identificadores generados automáticamente a partir de clics de visitantes en enlaces cortos o desde la biblioteca Hellotext.js al realizar un seguimiento de visitantes anónimos. Es una forma de rastrear eventos en el lado del cliente sin autenticar o divulgar el identificador de perfil permitiendo asociarlo más tarde a un perfil de forma segura en el lado del servidor.
tracked_at
Epoch
Fecha original en la que ocurrió el evento. Esto es útil si deseas registrar un evento que ocurrió en el pasado. Si no se proporciona ningún valor, su valor será el mismo que el de created_at.
url
URL
URL de la página donde ocurrió el evento. Si no se especifica, la URL se inferirá de la página actual. 
curl -X POST https://api.hellotext.com/v1/attribution/events 
 -d action="room.booked" 
 -d object="zGrDJ1Lb" 
 -d object_type=appointment 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
curl -X POST https://api.hellotext.com/v1/attribution/events 
 -d action="room.booked" 
 -d object_type=appointment 
 -d object_parameters[property_by_id][xGrDJ1Lb]="A-101" 
 -d object_parameters[property][booked at]="2021-01-01T12:00:00Z" 
 -d object_parameters[property][room]="A-101" 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "status": "received"
}

Acciones

Hellotext proporciona un conjunto básico de acciones, perfecto para comenzar tu próxima campaña de atribución. Pero, cuando surge la necesidad de rastrear diferentes acciones no proporcionadas por Hellotext, puedes ampliar el conjunto de acciones disponibles creando tus propias acciones personalizadas.

Puedes nombrar las acciones de la manera que desees. Recomendamos tomar un enfoque de puntos al nombrar tus 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.

Ejemplos de acciones personalizadas
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

Atributos
id
String
Identificador único del objeto.
type
Type
Tipo de objeto. Esto es siempre action.
created_at
Epoch
Fecha de creación del objeto.
goal
Boolean
¿Esta acción se utiliza como una métrica para KPIs? El valor predeterminado es false. Si se establece en true, los eventos con esta acción se pueden utilizar como una métrica para KPIs que se muestran en las Campañas y las Rutas.
name
String
El nombre de la acción. Este es el nombre que se usa en el parámetro action al momento de crear un evento. No se permiten nombres duplicados.
passive
Boolean
¿Esta acción es pasiva o no? El valor predeterminado es 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 tu equipo) y deseas verla fácilmente en la bandeja de entrada cuando suceda, mantén este atributo como false. Sin embargo, si la acción no es importante, puedes marcarla como pasiva.
title
String
Nombre alternativo de la acción utilizada en Segmentos y Rutas. Si no se proporciona, será el mismo que el parámetro de nombre. 
{
  "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.

Parámetros
goal
Boolean
¿Esta acción se utiliza como una métrica para KPIs? El valor predeterminado es false. Si se establece en true, los eventos con esta acción se pueden utilizar como una métrica para KPIs que se muestran en las Campañas y las Rutas.
name
String
Requerido
El nombre de la acción. Este es el nombre que se usa en el parámetro action al momento de crear un evento. No se permiten nombres duplicados.
passive
Boolean
¿Esta acción es pasiva o no? El valor predeterminado es true.
title
String
Nombre alternativo de la acción utilizada en Segmentos y Rutas. Si no se proporciona, será el mismo que el parámetro de nombre. 
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.

Parámetros
goal
Boolean
¿Esta acción se utiliza como una métrica para KPIs? El valor predeterminado es false. Si se establece en true, los eventos con esta acción se pueden utilizar como una métrica para KPIs que se muestran en las Campañas y las Rutas.
name
String
Requerido
El nombre de la acción. Este es el nombre que se usa en el parámetro action al momento de crear un evento. No se permiten nombres duplicados.
passive
Boolean
¿Esta acción es pasiva o no? El valor predeterminado es true.
title
String
Nombre alternativo de la acción utilizada en Segmentos y Rutas. Si no se proporciona, será el mismo que el parámetro de nombre. 
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. Ten 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.

Parámetros
ending_before
String
Mostrar resultados listados antes (más recientes) que el id dado.
limit
integer
Limitar cuántos resultados mostrar. El valor por defecto es 25. El máximo es 100.
starting_after
String
Mostrar resultados listados después (más antiguos) que el id dado. 
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"
    },
    "{...}",
    "{...}"
  ]
}

Aplicaciones

Los objetos App representan las aplicaciones que posees o administras y con las que interactúa tu audiencia. Por ejemplo, estas podrían ser tus aplicaciones de 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.

Los objetos App vienen con un conjunto de propiedades integradas. Además, puedes agregar tus propias propiedades personalizadas al objeto de la aplicación. Obtén más información sobre Objetos.

Más información 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 App

Atributos
id
String
Identificador único del objeto.
type
Type
Tipo de objeto. Esto es siempre app.
created_at
Epoch
Fecha de creación del objeto.
image_url
URL
Una URL que apunta a la imagen de la aplicación.
metadata
Hash
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
name
String
El nombre de la aplicación.
properties
array
Una lista de propiedades adicionales que se han agregado al Objeto. Mostrar atributos 
{
  "id": "xnqJQ47v",
  "type": "app",
  "created_at": 1665684173,
  "image_url": "https://example.com/image.jpg",
  "metadata": {},
  "name": "Beauty & Care",
  "properties": [
    {
      "id": "zGrDJ1Lb",
      "kind": "time",
      "value": {
        "id": "MQNKalb7",
        "kind": "time",
        "name": null,
        "value": {
          "day": 3,
          "month": 11,
          "year": 1985,
          "hour": 10,
          "minute": 10,
          "second": 10
        }
      },
      "property_id": "xxXxXxXx",
      "name": "Downloaded at"
    },
    {
      "id": "zGrDJ1Lb",
      "kind": "text",
      "value": "iPhone 16",
      "property_id": "xxXxXxXx",
      "name": "device"
    }
  ]
}

Crear una aplicación

Crea una nueva aplicación.

Parámetros
image_url
URL
Una URL del icono de la aplicación en alta resolución. Descargaremos la imagen y la almacenaremos en nuestros servidores.
metadata
Hash
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
name
String
Requerido
El nombre de la aplicación, sin distinción de mayúsculas y minúsculas. No se permiten nombres duplicados.
property[name]
String
Establece un valor de propiedad pasando el nombre de la propiedad, por ejemplo property[Active]=true. Esto es útil para establecer un valor para cualquier propiedad personalizada que hayas agregado al Objeto. Puedes eliminar una propiedad existente pasando null.
property_by_id[id]
String
Establece un valor de propiedad pasando el id de la propiedad, por ejemplo property_by_id[gVlpOkwJ]=true. Esto es útil para establecer un valor para cualquier propiedad personalizada que hayas agregado al Objeto. Puedes eliminar una propiedad existente pasando null. 
curl -X POST https://api.hellotext.com/v1/attribution/apps 
 -d name="Hellotext" 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "id": "xnqJQ47v",
  "type": "app",
  "created_at": 1665684173,
  "image_url": "https://example.com/image.jpg",
  "metadata": {},
  "name": "Hellotext",
  "properties": [
    {
      "id": "zGrDJ1Lb",
      "kind": "time",
      "value": {
        "id": "MQNKalb7",
        "kind": "time",
        "name": null,
        "value": {
          "day": 3,
          "month": 11,
          "year": 1985,
          "hour": 10,
          "minute": 10,
          "second": 10
        }
      },
      "property_id": "xxXxXxXx",
      "name": "Downloaded at"
    },
    {
      "id": "zGrDJ1Lb",
      "kind": "text",
      "value": "iPhone 16",
      "property_id": "xxXxXxXx",
      "name": "device"
    }
  ]
}

Recuperar una aplicación

Recupera una aplicación existente. 

curl -G https://api.hellotext.com/v1/attribution/apps/vxqQJ3Yg 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "id": "vxqQJ3Yg",
  "type": "app",
  "created_at": 1665684173,
  "image_url": "https://example.com/image.jpg",
  "metadata": {},
  "name": "Beauty & Care",
  "properties": [
    {
      "id": "zGrDJ1Lb",
      "kind": "time",
      "value": {
        "id": "MQNKalb7",
        "kind": "time",
        "name": null,
        "value": {
          "day": 3,
          "month": 11,
          "year": 1985,
          "hour": 10,
          "minute": 10,
          "second": 10
        }
      },
      "property_id": "xxXxXxXx",
      "name": "Downloaded at"
    },
    {
      "id": "zGrDJ1Lb",
      "kind": "text",
      "value": "iPhone 16",
      "property_id": "xxXxXxXx",
      "name": "device"
    }
  ]
}

Actualizar una aplicación

Actualiza una aplicación existente.

Atributos
image_url
URL
Una URL del icono de la aplicación en alta resolución. Descargaremos la imagen y la almacenaremos en nuestros servidores.
metadata
Hash
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
name
String
El nombre de la aplicación, sin distinción de mayúsculas y minúsculas. No se permiten nombres duplicados.
property[name]
String
Establece un valor de propiedad pasando el nombre de la propiedad, por ejemplo property[Active]=true. Esto es útil para establecer un valor para cualquier propiedad personalizada que hayas agregado al Objeto. Puedes eliminar una propiedad existente pasando null.
property_by_id[id]
String
Establece un valor de propiedad pasando el id de la propiedad, por ejemplo property_by_id[gVlpOkwJ]=true. Esto es útil para establecer un valor para cualquier propiedad personalizada que hayas agregado al Objeto. Puedes eliminar una propiedad existente pasando null. 
curl -X PATCH https://api.hellotext.com/v1/attribution/apps/:id 
 -d name="VIVA" 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "id": "xnqJQ47v",
  "type": "app",
  "created_at": 1665684173,
  "image_url": "https://example.com/image.jpg",
  "metadata": {},
  "name": "VIVA",
  "properties": [
    {
      "id": "zGrDJ1Lb",
      "kind": "time",
      "value": {
        "id": "MQNKalb7",
        "kind": "time",
        "name": null,
        "value": {
          "day": 3,
          "month": 11,
          "year": 1985,
          "hour": 10,
          "minute": 10,
          "second": 10
        }
      },
      "property_id": "xxXxXxXx",
      "name": "Downloaded at"
    },
    {
      "id": "zGrDJ1Lb",
      "kind": "text",
      "value": "iPhone 16",
      "property_id": "xxXxXxXx",
      "name": "device"
    }
  ]
}

Destruir una aplicación

Destruye una aplicación existente. 

curl -X DELETE https://api.hellotext.com/v1/attribution/apps/vxqQJ3Yg 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "id": "vxqQJ3Yg",
  "type": "app",
  "deleted": true
}

Listar todas las aplicaciones

Lista todas las aplicaciones.

Parámetros
ending_before
String
Mostrar resultados listados antes (más recientes) que el id dado.
limit
integer
Limitar cuántos resultados mostrar. El valor por defecto es 25. El máximo es 100.
starting_after
String
Mostrar resultados listados después (más antiguos) que el id dado. 
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://example.com/image.jpg",
      "metadata": {},
      "name": "Beauty & Care",
      "properties": [
        {
          "id": "zGrDJ1Lb",
          "kind": "time",
          "value": {
            "id": "MQNKalb7",
            "kind": "time",
            "name": null,
            "value": {
              "day": 3,
              "month": 11,
              "year": 1985,
              "hour": 10,
              "minute": 10,
              "second": 10
            }
          },
          "property_id": "xxXxXxXx",
          "name": "Downloaded at"
        },
        {
          "id": "zGrDJ1Lb",
          "kind": "text",
          "value": "iPhone 16",
          "property_id": "xxXxXxXx",
          "name": "device"
        }
      ]
    },
    "{...}",
    "{...}"
  ]
}

Carritos

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.

Los objetos de carrito vienen con un conjunto de propiedades integradas. Además, puedes agregar tus propias propiedades personalizadas al objeto de carrito. Obtén más información sobre Objetos.

Más información 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

Atributos
id
String
Identificador único del objeto.
type
Type
Tipo de objeto. Esto es siempre cart.
created_at
Epoch
Fecha de creación del objeto.
items
array
Una colección de elementos incluidos en el carrito en el momento actual. Mostrar atributos
metadata
Hash
Conjunto de pares clave-valor que puedes adjuntar al carrito. Esto puede ser útil para almacenar información adicional sobre el objeto en un formato estructurado.
profile
profile
El identificador del perfil al que pertenece este carrito.
properties
array
Una lista de propiedades adicionales que se han agregado al Objeto. Mostrar atributos
reference
String
El número de carrito o identificador original de la fuente externa que creó el carrito.
session
String
El identificador de la sesión a la que pertenece este carrito.
source
String
La fuente o plataforma de donde se generó este 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",
  "properties": [],
  "reference": "ABC123",
  "session": "Vdqlg4nL",
  "source": null
}

Crear un carrito

Crea un nuevo carrito.

Parámetros
items
array
Una colección de elementos de carrito que se incluyen en este carrito. Mostrar atributos
profile
profile
El identificador único del perfil al que pertenece este carrito. Requerido si no se proporciona session.
property[name]
String
Establece un valor de propiedad pasando el nombre de la propiedad, por ejemplo property[Active]=true. Esto es útil para establecer un valor para cualquier propiedad personalizada que hayas agregado al Objeto. Puedes eliminar una propiedad existente pasando null.
property_by_id[id]
String
Establece un valor de propiedad pasando el id de la propiedad, por ejemplo property_by_id[gVlpOkwJ]=true. Esto es útil para establecer un valor para cualquier propiedad personalizada que hayas agregado al Objeto. Puedes eliminar una propiedad existente pasando null.
reference
String
El número de carrito o identificador original de la fuente externa que creó el carrito.
session
String
"El identificador único de la sesión a la que pertenece este carrito. Requerido si no se proporciona 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."
source
String
La fuente o plataforma de donde se generó este carrito. 
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",
  "properties": [],
  "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.

Parámetros
items
array
"Una colección de elementos de carrito que reemplazan los elementos actuales en el carrito." "Pasando un valor vacío de [] eliminará todos los elementos del carrito." "Ignorar el parámetro no cambiará los elementos actuales en el carrito." Mostrar atributos
new_items
array
Una colección de nuevos elementos de carrito para agregar al carrito. Considera usar la API de seguimiento de carritos para agregar elementos a un carrito existente, ya que también se mostrará en el Rastro de Actividad de un Perfil. Mostrar atributos
profile
profile
El identificador único del perfil al que pertenece este carrito. Requerido si no se proporciona session.
property[name]
String
Establece un valor de propiedad pasando el nombre de la propiedad, por ejemplo property[Active]=true. Esto es útil para establecer un valor para cualquier propiedad personalizada que hayas agregado al Objeto. Puedes eliminar una propiedad existente pasando null.
property_by_id[id]
String
Establece un valor de propiedad pasando el id de la propiedad, por ejemplo property_by_id[gVlpOkwJ]=true. Esto es útil para establecer un valor para cualquier propiedad personalizada que hayas agregado al Objeto. Puedes eliminar una propiedad existente pasando null.
reference
String
El número de carrito o identificador original de la fuente externa que creó el carrito.
session
String
"El identificador único de la sesión a la que pertenece este carrito. Requerido si no se proporciona 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."
source
String
La fuente o plataforma de donde se generó este carrito. 
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",
  "properties": [],
  "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 carritos

Enumera los carritos existentes ordenados por los más recientes. Los parámetros de paginación están disponibles en listas.

Parámetros
ending_before
String
Mostrar resultados listados antes (más recientes) que el id dado.
limit
integer
Limitar cuántos resultados mostrar. El valor por defecto es 25. El máximo es 100.
starting_after
String
Mostrar resultados listados después (más antiguos) que el id dado. 
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",
      "properties": [],
      "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

Atributos
id
string
Identificador único del objeto de evento.
type
string
Tipo de objeto. Este es siempre event.
action
hash
Un hash que representa el objeto de acción. Mostrar atributos
amount
float
Monto monetario que representa los ingresos asociados a este evento. El valor predeterminado es null.
converted_amount
string
Importe monetario que representa los ingresos asociados a esta orden convertida a la moneda de informe del negocio.
converted_amount_currency
string
Moneda para el converted_amount proporcionada en formato ISO 4217.
created_at
epoch
Fecha de creación del objeto de evento.
currency
currency
Moneda para el cantidad proporcionada en formato ISO 4217. El valor predeterminado siempre es USD.
metadata
hash
Conjunto de pares atributo-valor que puedes adjuntar a un objeto. Esto puede ser útil para almacenar información adicional sobre el objeto en un formato estructurado.
profile
string
Obligatorio si no se especifica 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.
session
string
Obligatorio si no se especifica 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.
trackable
hash
Un hash que representa el objeto rastreado. Mostrar atributos
tracked_at
epoch
Fecha original en que ocurrió el evento. Esto es útil si deseas registrar un evento que sucedió en el pasado. Si no se proporciona ningún valor, su valor será el mismo de created_at.
url
url
La URL de la página donde ocurrió este evento. 
{
  "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.

Parámetros
action
string
El nombre de la acción.
amount
float
Monto monetario que representa los ingresos asociados a este evento. El valor predeterminado es null.
app
string
Identificador único del objeto de aplicación al que está asociado este evento.
currency
currency
Moneda para el cantidad proporcionada en formato ISO 4217. El valor predeterminado siempre es USD.
form
string
Identificador único del objeto de formulario al que está asociado este evento.
metadata
hash
Conjunto de pares atributo-valor que puedes adjuntar a un objeto. Esto puede ser útil para almacenar información adicional sobre el objeto en un formato estructurado.
order
string
Identificador único del objeto de orden al que está asociado este evento.
product
string
Identificador único del objeto de producto asociado a este evento.
product_ids
string
Una colección de identificadores de productos.
profile
string
Obligatorio si no se especifica 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
string
Identificador único del objeto de reembolso al que está asociado este evento.
session
string
Obligatorio si no se especifica 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.
tracked_at
epoch
Fecha original en que ocurrió el evento. Esto es útil si deseas registrar un evento que sucedió en el pasado. Si no se proporciona ningún valor, su valor será el mismo de created_at.
url
url
La URL de la página donde ocurrió este evento. 
        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.0,
  "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.

Parámetros
starting_after
string
Muestra los resultados después (más antiguos) que el identificador proporcionado.
ending_before
string
Muestra los resultados antes (más recientes) que el identificador proporcionado.
limit
integer
Limita la cantidad de resultados que se mostrarán. El valor predeterminado es 25. El máximo es 100. 
        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"
    },
    "{...}",
    "{...}"
  ]
}

Objetos

Un objeto representa un tipo de objeto personalizado que es específico para las necesidades de tu aplicación. Los objetos se utilizan para describir la estructura de los datos que usarán las instancias.

Cada negocio tiene acceso por defecto a la plantilla de objeto predeterminada, que puedes modificar según tus necesidades. Las propiedades de los objetos integrados no pueden editarse ni eliminarse, pero puedes agregar propiedades personalizadas adicionales a los objetos integrados.

Una vez creado, puedes usar la API de seguimiento para rastrear acciones específicas que el objeto haya realizado.

  • POST

    v1/objects

  • GET

    v1/objects/:id

  • PATCH

    v1/objects/:id

  • DELETE

    v1/objects/:id

  • GET

    v1/objects

Objetos

Atributos
id
String
Identificador único del objeto.
type
Type
Tipo de objeto. Esto es siempre object.
created_at
Epoch
Fecha de creación del objeto.
kind
Enum
El tipo de objeto. Esto es custom para cualquier objeto adicional que crees.
Valores enum posibles
app
cart
custom
form
location
order
product
refund
name
String
El nombre parametrizado del objeto. Se utiliza al rastrear eventos a través de la API. Por ejemplo, si el nombre del objeto es appointment, puedes usar appointment=id para rastrear una cita existente, o usar appointment_params para crear un nuevo objeto al rastrear.
properties
array
Las propiedades del objeto. Esta lista determina la estructura que tendrá cada instancia del objeto, si es única y/o requerida.

Las propiedades integradas no se pueden modificar, pero pueden reordenarse junto con las nuevas propiedades que introduzcas. Mostrar atributos
title
String
El nombre humanizado, utilizado en todo el panel de control. 
{
  "id": "zGrDJ1Lb",
  "type": "object",
  "created_at": 1739128395,
  "kind": "custom",
  "name": "appointment",
  "properties": [
    {
      "id": "zGrDJ1Lb",
      "kind": "text",
      "required": false,
      "modifiable": true,
      "name": "room",
      "unique": false
    },
    {
      "id": "zGrDJ1Lb",
      "kind": "time",
      "required": true,
      "modifiable": true,
      "name": "Booked at",
      "unique": false
    }
  ],
  "title": "Appointment"
}

Crear objeto

Crea un nuevo objeto.

Parámetros
name
String
Requerido
El nombre parametrizado del objeto. Se utiliza al rastrear eventos a través de la API. Por ejemplo, si el nombre del objeto es appointment, puedes usar appointment=id para rastrear una cita existente, o usar appointment_params para crear un nuevo objeto al rastrear.
properties
array
Las propiedades del objeto. Esta lista determina la estructura que tendrá cada instancia del objeto, si es única y/o requerida.

Las propiedades integradas no se pueden modificar, pero pueden reordenarse junto con las nuevas propiedades que introduzcas. Mostrar atributos
title
String
Requerido
El nombre humanizado, utilizado en todo el panel de control. 
curl -X POST https://api.hellotext.com/v1/objects 
 -d name="appointment" 
 -d title="Appointment" 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "id": "zGrDJ1Lb",
  "type": "object",
  "created_at": 1739128395,
  "kind": "custom",
  "name": "appointment",
  "properties": [
    {
      "id": "zGrDJ1Lb",
      "kind": "text",
      "required": false,
      "modifiable": true,
      "name": "room",
      "unique": false
    },
    {
      "id": "zGrDJ1Lb",
      "kind": "time",
      "required": true,
      "modifiable": true,
      "name": "Booked at",
      "unique": false
    }
  ],
  "title": "Appointment"
}

Obtener un objeto

Obtiene un objeto existente. 

curl -G https://api.hellotext.com/v1/objects/vxqQJ3Yg 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "id": "vxqQJ3Yg",
  "type": "object",
  "created_at": 1739128395,
  "kind": "custom",
  "name": "appointment",
  "properties": [
    {
      "id": "zGrDJ1Lb",
      "kind": "text",
      "required": false,
      "modifiable": true,
      "name": "room",
      "unique": false
    },
    {
      "id": "zGrDJ1Lb",
      "kind": "time",
      "required": true,
      "modifiable": true,
      "name": "Booked at",
      "unique": false
    }
  ],
  "title": "Appointment"
}

Actualizar un objeto

Actualiza un objeto existente.

Atributos
name
String
Requerido
El nombre parametrizado del objeto. Se utiliza al rastrear eventos a través de la API. Por ejemplo, si el nombre del objeto es appointment, puedes usar appointment=id para rastrear una cita existente, o usar appointment_params para crear un nuevo objeto al rastrear.
properties
array
The properties of the object. This list determines the shape each instance of the object will have. Whether it is unique, and/or required.

If an entry contains an id, then that property will be updated. Any entries without an id will be created and appended to the end of the properties list unless a position is specified. Mostrar atributos
title
String
Requerido
El nombre humanizado, utilizado en todo el panel de control. 
curl -X PATCH https://api.hellotext.com/v1/objects/vxqQJ3Yg 
 -d name="customer" 
 -d title="Customers" 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "id": "vxqQJ3Yg",
  "type": "object",
  "created_at": 1739128395,
  "kind": "custom",
  "name": "customer",
  "properties": [
    {
      "id": "zGrDJ1Lb",
      "kind": "text",
      "required": false,
      "modifiable": true,
      "name": "room",
      "unique": false
    },
    {
      "id": "zGrDJ1Lb",
      "kind": "time",
      "required": true,
      "modifiable": true,
      "name": "Booked at",
      "unique": false
    }
  ],
  "title": "Customers"
}

Eliminar un objeto

Elimina un objeto existente. 

curl -X DELETE https://api.hellotext.com/v1/objects/vxqQJ3Yg 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "id": "vxqQJ3Yg",
  "type": "object",
  "deleted": true
}

Listar objetos

Lista todos los objetos existentes.

Parámetros
ending_before
String
Mostrar resultados listados antes (más recientes) que el id dado.
limit
integer
Limitar cuántos resultados mostrar. El valor por defecto es 25. El máximo es 100.
starting_after
String
Mostrar resultados listados después (más antiguos) que el id dado. 
curl -G https://api.hellotext.com/v1/objects 
 -d limit=5 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "objects": [
    {
      "id": "zGrDJ1Lb",
      "type": "object",
      "created_at": 1739128395,
      "kind": "custom",
      "name": "appointment",
      "properties": [
        {
          "id": "zGrDJ1Lb",
          "kind": "text",
          "required": false,
          "modifiable": true,
          "name": "room",
          "unique": false
        },
        {
          "id": "zGrDJ1Lb",
          "kind": "time",
          "required": true,
          "modifiable": true,
          "name": "Booked at",
          "unique": false
        }
      ],
      "title": "Appointment"
    },
    "{...}",
    "{...}"
  ]
}

El objeto orden

Las órdenes representan grupos de productos que puedes usar al rastrear los eventos order.placed, order.confirmed, order.shipped, order.cancelled y order.delivered.

Los objetos de orden vienen con un conjunto de propiedades integradas. Además, puedes agregar tus propias propiedades personalizadas al objeto de orden. Obtén más información sobre Objetos.

Más información Eventos de órdenes.

  • 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 orden

Atributos
id
String
Identificador único del objeto de orden.
type
Type
Tipo de objeto. Siempre es order.
created_at
Epoch
Fecha de creación del objeto de orden.
delivery
Enum
Especifica cómo se debe entregar la orden al cliente. Se puede usar en Rutas para establecer diferentes condiciones basadas en este valor. Los valores posibles son 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.
Valores enum posibles
collect
deliver
items
array
Una colección de productos incluidos en la orden. Mostrar atributos
metadata
hash
Conjunto de pares atributo-valor que puedes adjuntar a un objeto. Esto puede ser útil para almacenar información adicional sobre el objeto en un formato estructurado.
name
String
Cualquier nombre dado a la orden de referencia. No se permiten nombres duplicados.
payment_method
String
Enumera los métodos de pago separados por comas utilizados para pagar este pedido. Por ejemplo, VISA, Mastercard, Shop Pay
properties
array
Una lista de propiedades adicionales que se han agregado al Objeto. Mostrar atributos
reference
String
El número de orden o el identificador original de la fuente externa que creó la orden.
sales_channel
String
Nombre del canal donde se generó la orden, por ejemplo, website, app, external, etc.
source
String
El identificador de la plataforma donde se creó la orden.
total
hash
Un hash que representa el total y el total convertido del orden. Mostrar atributos 
{
  "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": {},
  "name": "Order 1",
  "payment_method": "Mastercard",
  "sales_channel": "Website",
  "properties": [],
  "reference": "1234",
  "source": null,
  "total": {
    "amount": "395.00",
    "converted_amount": "19.90",
    "converted_amount_currency": "EUR",
    "currency": "USD"
  }
}

Crear una orden

Crea una nueva orden.

Atributos
delivery
Enum
Especifica cómo se debe entregar la orden al cliente. Se puede usar en Rutas para establecer diferentes condiciones basadas en este valor. Los valores posibles son 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.
Valores enum posibles
collect
deliver
items
array
Una colección de productos incluidos en la orden. Mostrar atributos
metadata
hash
Conjunto de pares atributo-valor que puedes adjuntar a un objeto. Esto puede ser útil para almacenar información adicional sobre el objeto en un formato estructurado.
payment_method
String
Enumera los métodos de pago separados por comas utilizados para pagar este pedido. Por ejemplo, VISA, Mastercard, Shop Pay
property[name]
String
Establece un valor de propiedad pasando el nombre de la propiedad, por ejemplo property[Active]=true. Esto es útil para establecer un valor para cualquier propiedad personalizada que hayas agregado al Objeto. Puedes eliminar una propiedad existente pasando null.
property_by_id[id]
String
Establece un valor de propiedad pasando el id de la propiedad, por ejemplo property_by_id[gVlpOkwJ]=true. Esto es útil para establecer un valor para cualquier propiedad personalizada que hayas agregado al Objeto. Puedes eliminar una propiedad existente pasando null.
reference
String
El número de orden o el identificador original de la fuente externa que creó la orden.
sales_channel
String
Nombre del canal donde se generó la orden, por ejemplo, website, app, external, etc.
source
String
El identificador de la plataforma donde se creó la orden. 
curl -X POST https://api.hellotext.com/v1/attribution/orders 
 -d reference="vxqQJ3YQ" 
 -d source="shopify" 
 -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": {},
  "name": "Order 1",
  "payment_method": "Mastercard",
  "sales_channel": "Website",
  "properties": [],
  "reference": "vxqQJ3YQ",
  "source": "shopify",
  "total": {
    "amount": "395.00",
    "converted_amount": "19.90",
    "converted_amount_currency": "EUR",
    "currency": "USD"
  }
}

Recuperar una orden

Recupera los detalles de una 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": {},
  "name": "Order 1",
  "payment_method": "Mastercard",
  "sales_channel": "Website",
  "properties": [],
  "reference": "1234",
  "source": null,
  "total": {
    "amount": "395.00",
    "converted_amount": "19.90",
    "converted_amount_currency": "EUR",
    "currency": "USD"
  }
}

Actualizar una orden

Actualiza una orden existente.

Atributos
delivery
Enum
Especifica cómo se debe entregar la orden al cliente. Se puede usar en Rutas para establecer diferentes condiciones basadas en este valor. Los valores posibles son 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.
Valores enum posibles
collect
deliver
metadata
hash
Conjunto de pares atributo-valor que puedes adjuntar a un objeto. Esto puede ser útil para almacenar información adicional sobre el objeto en un formato estructurado.
payment_method
String
Enumera los métodos de pago separados por comas utilizados para pagar este pedido. Por ejemplo, VISA, Mastercard, Shop Pay
property[name]
String
Establece un valor de propiedad pasando el nombre de la propiedad, por ejemplo property[Active]=true. Esto es útil para establecer un valor para cualquier propiedad personalizada que hayas agregado al Objeto. Puedes eliminar una propiedad existente pasando null.
property_by_id[id]
String
Establece un valor de propiedad pasando el id de la propiedad, por ejemplo property_by_id[gVlpOkwJ]=true. Esto es útil para establecer un valor para cualquier propiedad personalizada que hayas agregado al Objeto. Puedes eliminar una propiedad existente pasando null.
reference
String
El número de orden o el identificador original de la fuente externa que creó la orden.
sales_channel
String
Nombre del canal donde se generó la orden, por ejemplo, website, app, external, etc.
source
String
El identificador de la plataforma donde se creó la orden. 
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": {},
  "name": "Yeezy boost 350 v2",
  "payment_method": "Mastercard",
  "sales_channel": "Website",
  "properties": [],
  "reference": "1234",
  "source": null,
  "total": {
    "amount": "395.00",
    "converted_amount": "19.90",
    "converted_amount_currency": "EUR",
    "currency": "USD"
  },
  "sku": "5678"
}

Eliminar una orden

Elimina una orden.

 
curl -X DELETE https://api.hellotext.com/v1/attribution/orders/vxqQJ3Yg 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "id": "vxqQJ3Yg",
  "type": "order",
  "deleted": true
}

Listar todas las órdenes

Enumera las órdenes existentes ordenadas por las más recientes. Los parámetros de paginación están disponibles en listas.

Parámetros
ending_before
String
Mostrar resultados listados antes (más recientes) que el id dado.
limit
integer
Limitar cuántos resultados mostrar. El valor por defecto es 25. El máximo es 100.
starting_after
String
Mostrar resultados listados después (más antiguos) que el id dado. 
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": {},
      "name": "Order 1",
      "payment_method": "Mastercard",
      "sales_channel": "Website",
      "properties": [],
      "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.

Atributos
id
String
El identificador único del elemento del orden.
type
Type
El tipo del objeto. Esto siempre es order_item.
created_at
Epoch
Fecha de creación del objeto.
price
hash
Un hash que representa el precio y el precio convertido del elemento del orden. Mostrar atributos
product
product
El identificador único del producto.
quantity
float
La cantidad del producto en 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.

Atributos
price
hash
Un hash que representa el precio y el precio convertido del elemento del carrito. Cuando no se especifica, la propiedad se heredará del product. Mostrar atributos
product
product
Requerido
Un identificador único (id, reference o sku) de un producto o variante de producto.
quantity
float
La cantidad del producto que se agregará al carrito. Por defecto es 1. 
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.

Atributos
price
hash
Un hash que representa el precio y el precio convertido del elemento del carrito. Cuando no se especifica, la propiedad se heredará del product. Mostrar atributos
quantity
float
La cantidad del producto que se agregará al carrito. Por defecto es 1. 
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.

Los objetos de producto vienen con un conjunto de propiedades integradas. Además, puedes agregar tus propias propiedades personalizadas al objeto de producto. Obtén más información sobre Objetos.

Más información Eventos de productos.

  • 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

Atributos
id
String
Identificador único del objeto.
type
Type
Tipo de objeto. Esto es siempre product.
brand
String
Nombre de la marca del producto.
categories
array
Una colección de categorías representadas como una colección de valores de texto.
collection
array
Nombre de colección para productos que pertenecen a una colección.
created_at
Epoch
Fecha de creación del objeto producto.
image_url
URL
Una URL del producto en alta resolución.
metadata
Hash
Conjunto de pares atributo-valor que puedes adjuntar a un objeto. Esto puede ser útil para almacenar información adicional sobre el objeto en un formato estructurado.
name
String
Cualquier nombre asignado al producto como referencia. Este también es el nombre de la variante predeterminada.
price
hash
Un hash que representa la moneda del producto y el identificador asociado. También contiene el converted_amount y converted_identifier. Mostrar atributos
properties
array
Una lista de propiedades adicionales que se han agregado al Objeto. Mostrar atributos
reference
String
El número de producto o el identificador original de la fuente externa que creó el producto.
sku
String
Un identificador que distingue entre mayúsculas y minúsculas para la variante predeterminada del producto. Para un seguimiento y reporte de ventas efectivos, los SKUs deben ser únicos y ninguna variante de producto debe incluir el mismo SKU en sus detalles.
source
String
La fuente o plataforma de donde se generó este producto. Corresponde a la primera variante.
tags
array
Una colección de etiquetas representadas como una matriz de cadenas.
variants
array
Un array de todas las variantes del producto actual. Cada matriz contiene los aspectos únicos de la variante en comparación con el padre. Cada variante contiene un atributo id que puede utilizar para eliminar o actualizar esa variante específica. Mostrar atributos 
{
  "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"
  },
  "properties": [],
  "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",
      "properties": [],
      "reference": null,
      "sku": "1234567890",
      "source": null
    },
    "{...}",
    "{...}"
  ]
}

Crear un producto

Crea un nuevo producto.

Parámetros
brand
String
Nombre de la marca del producto.
categories
array
Una colección de categorías representadas como una colección de valores de texto.
collection
array
Nombre de colección para productos que pertenecen a una colección.
image_url
URL
Una URL que apunta a una imagen del producto. Descargaremos la imagen y la almacenaremos en nuestros servidores. Asegúrate de que la URL sea de acceso público porque no podremos acceder a ella si requiere autenticación.
metadata
Hash
Conjunto de pares atributo-valor que puedes adjuntar a un objeto. Esto puede ser útil para almacenar información adicional sobre el objeto en un formato estructurado.
name
String
Requerido
Cualquier nombre asignado al producto como referencia. Este también es el nombre de la variante predeterminada.
price
hash
Un hash que representa la moneda del producto y el identificador asociado. También contiene el converted_amount y converted_identifier. Mostrar atributos
property[name]
String
Establece un valor de propiedad pasando el nombre de la propiedad, por ejemplo property[Active]=true. Esto es útil para establecer un valor para cualquier propiedad personalizada que hayas agregado al Objeto. Puedes eliminar una propiedad existente pasando null.
property_by_id[id]
String
Establece un valor de propiedad pasando el id de la propiedad, por ejemplo property_by_id[gVlpOkwJ]=true. Esto es útil para establecer un valor para cualquier propiedad personalizada que hayas agregado al Objeto. Puedes eliminar una propiedad existente pasando null.
reference
String
El número de producto o el identificador original de la fuente externa que creó el producto.
sku
String
Un identificador que distingue entre mayúsculas y minúsculas para la variante predeterminada del producto. Para un seguimiento y reporte de ventas efectivos, los SKUs deben ser únicos y ninguna variante de producto debe incluir el mismo SKU en sus detalles.
source
String
La fuente o plataforma de donde se generó este producto. Corresponde a la primera variante.
tags
array
Una colección de etiquetas representadas como una matriz de cadenas.
variants
array
Un array de hashes clave-valor que representan las variantes. Se crea una variante para cada elemento en el array. Mostrar atributos 
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"
  },
  "properties": [],
  "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",
      "properties": [],
      "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.

Parámetros
brand
String
Nombre de la marca del producto.
categories
array
Una colección de categorías representadas como una colección de valores de texto.
collection
array
Nombre de colección para productos que pertenecen a una colección.
image_url
URL
Una URL que apunta a una imagen del producto. Descargaremos la imagen y la almacenaremos en nuestros servidores. Asegúrate de que la URL sea de acceso público porque no podremos acceder a ella si requiere autenticación.
metadata
Hash
Conjunto de pares atributo-valor que puedes adjuntar a un objeto. Esto puede ser útil para almacenar información adicional sobre el objeto en un formato estructurado.
name
String
Cualquier nombre asignado al producto como referencia. Este también es el nombre de la variante predeterminada.
new_variants
array
Un array de nuevas variantes para agregar al producto. Cada variante es un hash de pares clave-valor. Mostrar atributos
price
hash
Un hash que representa la moneda del producto y el identificador asociado. También contiene el converted_amount y converted_identifier. Mostrar atributos
property[name]
String
Establece un valor de propiedad pasando el nombre de la propiedad, por ejemplo property[Active]=true. Esto es útil para establecer un valor para cualquier propiedad personalizada que hayas agregado al Objeto. Puedes eliminar una propiedad existente pasando null.
property_by_id[id]
String
Establece un valor de propiedad pasando el id de la propiedad, por ejemplo property_by_id[gVlpOkwJ]=true. Esto es útil para establecer un valor para cualquier propiedad personalizada que hayas agregado al Objeto. Puedes eliminar una propiedad existente pasando null.
reference
String
El número de producto o el identificador original de la fuente externa que creó el producto.
sku
String
Un identificador que distingue entre mayúsculas y minúsculas para la variante predeterminada del producto. Para un seguimiento y reporte de ventas efectivos, los SKUs deben ser únicos y ninguna variante de producto debe incluir el mismo SKU en sus detalles.
tags
array
Una colección de etiquetas representadas como una matriz de cadenas.
variants
array
Pasar un array vacío [] eliminará todas las variantes existentes del producto. Asegúrate de usar new_variants para agregar nuevas variantes al producto. Mostrar atributos 
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"
  },
  "properties": [],
  "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",
      "properties": [],
      "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.

Parámetros
ending_before
String
Mostrar resultados listados antes (más recientes) que el id dado.
limit
integer
Limitar cuántos resultados mostrar. El valor por defecto es 25. El máximo es 100.
starting_after
String
Mostrar resultados listados después (más antiguos) que el id dado. 
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"
      },
      "properties": [],
      "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",
          "properties": [],
          "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.

Los objetos de producto vienen con un conjunto de propiedades integradas. Además, puedes agregar tus propias propiedades personalizadas al objeto de producto. Obtén más información sobre Objetos.

Más información Eventos de productos.

  • 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

Atributos
id
String
Unique identifier of the product variant object.
type
Type
Type of object. This is always product_variant.
created_at
Epoch
Date of creation of the product variant object.
image_url
URL
URL of the image associated with the product variant.
metadata
Hash
Conjunto de pares atributo-valor que puedes adjuntar a un objeto. Esto puede ser útil para almacenar información adicional sobre el objeto en un formato estructurado.
name
String
Cualquier nombre dado a la variante como referencia.
price
hash
Un hash que representa la moneda del producto y el identificador asociado. También contiene el converted_amount y converted_identifier. Mostrar atributos
product
product
Identificador del objeto de producto asociado a esta variante.
properties
array
Una lista de propiedades adicionales que se han agregado al Objeto. Mostrar atributos
reference
String
El número de variante o el identificador original de la fuente externa que creó la variante.
sku
String
Un identificador que distingue entre mayúsculas y minúsculas para la variante del producto. Para un seguimiento y reporte de ventas efectivos, los SKUs deben ser únicos y ninguna variante de producto debe incluir el mismo SKU en sus detalles.
source
String
La fuente o plataforma de donde se generó esta variante de producto. Esto siempre es el mismo que el producto principal. 
{
  "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",
  "properties": [],
  "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.

Atributos
image_url
URL
Una URL que apunta a una imagen de la variante. Descargaremos la imagen y la almacenaremos en nuestros servidores. Asegúrate de que la URL sea de acceso público porque no podremos acceder a ella si requiere autenticación.
metadata
Hash
Conjunto de pares atributo-valor que puedes adjuntar a un objeto. Esto puede ser útil para almacenar información adicional sobre el objeto en un formato estructurado.
name
String
Requerido
Cualquier nombre dado a la variante como referencia.
price
hash
Un hash que representa la moneda del producto y el identificador asociado. También contiene el converted_amount y converted_identifier. Mostrar atributos
property[name]
String
Establece un valor de propiedad pasando el nombre de la propiedad, por ejemplo property[Active]=true. Esto es útil para establecer un valor para cualquier propiedad personalizada que hayas agregado al Objeto. Puedes eliminar una propiedad existente pasando null.
property_by_id[id]
String
Establece un valor de propiedad pasando el id de la propiedad, por ejemplo property_by_id[gVlpOkwJ]=true. Esto es útil para establecer un valor para cualquier propiedad personalizada que hayas agregado al Objeto. Puedes eliminar una propiedad existente pasando null.
reference
String
El número de variante o el identificador original de la fuente externa que creó la variante.
sku
String
Un identificador que distingue entre mayúsculas y minúsculas para la variante del producto. Para un seguimiento y reporte de ventas efectivos, los SKUs deben ser únicos y ninguna variante de producto debe incluir el mismo SKU en sus detalles.
source
String
La fuente o plataforma de donde se generó esta variante de producto. Esto siempre es el mismo que el producto principal. 
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",
  "properties": [],
  "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.

Atributos
image_url
URL
Una URL que apunta a una imagen de la variante. Descargaremos la imagen y la almacenaremos en nuestros servidores. Asegúrate de que la URL sea de acceso público porque no podremos acceder a ella si requiere autenticación.
metadata
Hash
Conjunto de pares atributo-valor que puedes adjuntar a un objeto. Esto puede ser útil para almacenar información adicional sobre el objeto en un formato estructurado.
name
String
Requerido
Cualquier nombre dado a la variante como referencia.
price
hash
Un hash que representa la moneda del producto y el identificador asociado. También contiene el converted_amount y converted_identifier. Mostrar atributos
property[name]
String
Establece un valor de propiedad pasando el nombre de la propiedad, por ejemplo property[Active]=true. Esto es útil para establecer un valor para cualquier propiedad personalizada que hayas agregado al Objeto. Puedes eliminar una propiedad existente pasando null.
property_by_id[id]
String
Establece un valor de propiedad pasando el id de la propiedad, por ejemplo property_by_id[gVlpOkwJ]=true. Esto es útil para establecer un valor para cualquier propiedad personalizada que hayas agregado al Objeto. Puedes eliminar una propiedad existente pasando null.
reference
String
El número de variante o el identificador original de la fuente externa que creó la variante.
sku
String
Un identificador que distingue entre mayúsculas y minúsculas para la variante del producto. Para un seguimiento y reporte de ventas efectivos, los SKUs deben ser únicos y ninguna variante de producto debe incluir el mismo SKU en sus detalles.
source
String
La fuente o plataforma de donde se generó esta variante de producto. Esto siempre es el mismo que el producto principal. 
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",
  "properties": [],
  "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 puedes usar para rastrear acciones a través de su ciclo de vida, como reembolso.solicitado y reembolso.recibido.

Los objetos de reembolso vienen con un conjunto de propiedades integradas. Además, puedes agregar tus propias propiedades personalizadas al objeto de reembolso. Obtén más información sobre Objetos.

Más información Eventos de reembolsos.

  • 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 de reembolso

Atributos
id
String
Identificador único del objeto.
type
Type
Tipo de objeto. Esto es siempre refund.
created_at
Epoch
Fecha de creación del objeto.
metadata
Hash
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
profile
String
Identificador del objeto de perfil asociado a este reembolso.
properties
array
Una lista de propiedades adicionales que se han agregado al Objeto. Mostrar atributos
reference
String
El número de reembolso o identificador original de la fuente externa que creó el reembolso.
refundable
String
El objeto reembolsable. Hash que representa el pedido o producto asociado reembolsado.
source
String
El identificador de la plataforma donde se creó el reembolso.
total
hash
Un hash que representa el total y el total convertido del reembolso. Mostrar atributos 
{
  "id": "w83Pj4PY",
  "type": "refund",
  "created_at": 1665684173,
  "metadata": {},
  "profile": null,
  "properties": [],
  "reference": null,
  "refundable": {
    "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": {},
    "name": "Order 1",
    "payment_method": "Mastercard",
    "sales_channel": "Website",
    "properties": [],
    "reference": "1234",
    "source": null,
    "total": {
      "amount": "395.00",
      "converted_amount": "19.90",
      "converted_amount_currency": "EUR",
      "currency": "USD"
    }
  },
  "source": null,
  "total": {
    "amount": 199.95,
    "converted_amount": 199.95,
    "converted_currency": "EUR",
    "currency": "USD"
  }
}

Crea un reembolso

Crea un nuevo reembolso.

Parámetros
metadata
Hash
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
order
String
Identificador del objeto de pedido asociado a este reembolso. El pedido se establecerá como el objeto reembolsable.
product
String
Identificador del objeto de producto asociado a este reembolso. El producto se establecerá como el objeto reembolsable.
profile
String
Identificador del objeto de perfil asociado a este reembolso.
property[name]
String
Establece un valor de propiedad pasando el nombre de la propiedad, por ejemplo property[Active]=true. Esto es útil para establecer un valor para cualquier propiedad personalizada que hayas agregado al Objeto. Puedes eliminar una propiedad existente pasando null.
property_by_id[id]
String
Establece un valor de propiedad pasando el id de la propiedad, por ejemplo property_by_id[gVlpOkwJ]=true. Esto es útil para establecer un valor para cualquier propiedad personalizada que hayas agregado al Objeto. Puedes eliminar una propiedad existente pasando null.
reference
String
El número de reembolso o identificador original de la fuente externa que creó el reembolso.
source
String
El identificador de la plataforma donde se creó el reembolso.
total
hash
Un hash que representa el total y el total convertido del reembolso.
total
hash
Un hash que representa el total y el total convertido del reembolso. Mostrar atributos 
curl -X POST https://api.hellotext.com/v1/attribution/refunds 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "id": "w83Pj4PY",
  "type": "refund",
  "created_at": 1665684173,
  "metadata": {},
  "profile": null,
  "properties": [],
  "reference": null,
  "refundable": {
    "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": {},
    "name": "Order 1",
    "payment_method": "Mastercard",
    "sales_channel": "Website",
    "properties": [],
    "reference": "1234",
    "source": null,
    "total": {
      "amount": "395.00",
      "converted_amount": "19.90",
      "converted_amount_currency": "EUR",
      "currency": "USD"
    }
  },
  "source": null,
  "total": {
    "amount": 199.95,
    "converted_amount": 199.95,
    "converted_currency": "EUR",
    "currency": "USD"
  }
}

Recupera un reembolso

Recupera un reembolso existente. 

curl -G https://api.hellotext.com/v1/attribution/refunds/vxqQJ3Yg 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "id": "vxqQJ3Yg",
  "type": "refund",
  "created_at": 1665684173,
  "metadata": {},
  "profile": null,
  "properties": [],
  "reference": null,
  "refundable": {
    "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": {},
    "name": "Order 1",
    "payment_method": "Mastercard",
    "sales_channel": "Website",
    "properties": [],
    "reference": "1234",
    "source": null,
    "total": {
      "amount": "395.00",
      "converted_amount": "19.90",
      "converted_amount_currency": "EUR",
      "currency": "USD"
    }
  },
  "source": null,
  "total": {
    "amount": 199.95,
    "converted_amount": 199.95,
    "converted_currency": "EUR",
    "currency": "USD"
  }
}

Actualiza un reembolso

Actualiza un reembolso existente.

Atributos
metadata
Hash
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
order
String
Identificador del objeto de pedido asociado a este reembolso. El pedido se establecerá como el objeto reembolsable.
product
String
Identificador del objeto de producto asociado a este reembolso. El producto se establecerá como el objeto reembolsable.
profile
String
Identificador del objeto de perfil asociado a este reembolso.
property[name]
String
Establece un valor de propiedad pasando el nombre de la propiedad, por ejemplo property[Active]=true. Esto es útil para establecer un valor para cualquier propiedad personalizada que hayas agregado al Objeto. Puedes eliminar una propiedad existente pasando null.
property_by_id[id]
String
Establece un valor de propiedad pasando el id de la propiedad, por ejemplo property_by_id[gVlpOkwJ]=true. Esto es útil para establecer un valor para cualquier propiedad personalizada que hayas agregado al Objeto. Puedes eliminar una propiedad existente pasando null.
reference
String
El número de reembolso o identificador original de la fuente externa que creó el reembolso.
source
String
El identificador de la plataforma donde se creó el reembolso.
total
hash
Un hash que representa el total y el total convertido del reembolso.
total
hash
Un hash que representa el total y el total convertido del reembolso. Mostrar atributos 
curl -X PATCH https://api.hellotext.com/v1/attribution/refunds/:id 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "id": "w83Pj4PY",
  "type": "refund",
  "created_at": 1665684173,
  "metadata": {},
  "profile": null,
  "properties": [],
  "reference": null,
  "refundable": {
    "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": {},
    "name": "Order 1",
    "payment_method": "Mastercard",
    "sales_channel": "Website",
    "properties": [],
    "reference": "1234",
    "source": null,
    "total": {
      "amount": "395.00",
      "converted_amount": "19.90",
      "converted_amount_currency": "EUR",
      "currency": "USD"
    }
  },
  "source": null,
  "total": {
    "amount": 199.95,
    "converted_amount": 199.95,
    "converted_currency": "EUR",
    "currency": "USD"
  }
}

Destruye un reembolso

Destruye un reembolso existente. 

curl -X DELETE https://api.hellotext.com/v1/attribution/refunds/vxqQJ3Yg 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "id": "vxqQJ3Yg",
  "type": "refund",
  "deleted": true
}

Lista todos los reembolsos

Lista todos los reembolsos.

Parámetros
ending_before
String
Mostrar resultados listados antes (más recientes) que el id dado.
limit
integer
Limitar cuántos resultados mostrar. El valor por defecto es 25. El máximo es 100.
starting_after
String
Mostrar resultados listados después (más antiguos) que el id dado. 
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,
      "properties": [],
      "reference": null,
      "refundable": {
        "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": {},
        "name": "Order 1",
        "payment_method": "Mastercard",
        "sales_channel": "Website",
        "properties": [],
        "reference": "1234",
        "source": null,
        "total": {
          "amount": "395.00",
          "converted_amount": "19.90",
          "converted_amount_currency": "EUR",
          "currency": "USD"
        }
      },
      "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

Adjuntar sesión

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 adjuntas la sesión.

Puedes pasar el identificador uuid de la sesión generado desde el cliente o el id de la sesión en el parámetro :id a la API para realizar operaciones en la sesión.

Parámetros
profile
string
Requerido
El perfil para asignar la sesión y sus eventos rastreados. 
        curl https://api.hellotext.com/v1/sessions/WBAkaqNz \
        -d profile=MzYwlE50 \
        -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "id": "WBAkaqNz",
  "type": "session",
  "profile": "MzYwlE50",
  "created_at": 1665684173,
  "uuid": "730a8d6b-fe22-4df0-b517-cc2e8197bd67"
}