Sign In Get a Demo

API Reference

Hellotext provides a powerful REST API designed for developer happiness. We make constant efforts in keeping all resources and actions simple and consistent.

All responses are formatted and returned in JSON.

 
https://api.hellotext.com

Authentication

All requests to the API must to be authenticated. Authentication is performed by sending a token with each request to the API.

You can create and manage your authorization tokens from the business settings page. All authorizations tokens are specific to the business it was created from.

To authenticate make sure to include an authorization header with the format Authorization: Bearer {token}. Replace the token with the authorization token.

 
curl https://api.hellotext.com/v1/profiles \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

Errors

Hellotext uses conventional HTTP response codes to indicate status of a request. When a request is valid but does not complete as expected we return a 422 error and a errors JSON object is attached to the object including a collection of errors including type and description.

Attributes
type
string
A code that represents the error in string format.
message
string
A detailed description of the error.
parameter
string
Name of the parameter associated to the error.
400 Bad Request
Often missing a required parameter.
401 Unauthorized
No valid API key.
404 Not Found
The requested item does not exist.
422 Request Failed
Parameters were valid but request failed.
500, 502, 503, 504 Server errors
Something went wrong.
ambiguous_parameter
One or more possible parameters were provided for the same role. Specify at least one of the possible values.
invalid
The value you provided for the parameter is not correct. Please check the documentation for the correct value.
not_allowed
The operation is not allowed. Usually because the object is in a state that does not allow the action.
not_found
This object was not found. Perhaps it was deleted.
object_invalid
At least one of the optional parameters must be provided.
parameter_invalid_empty
This required parameter has an empty value. Provide a valid value for the parameter.
parameter_missing
This parameter is required.
parameter_not_unique
The value must be unique and it is already present in another object of the same type.
session_assigned_to_another_profile
This session has been assigned to another profile. It cannot be used to track events for the current profile.
undefined_property
You tried to set a property on a profile that did not exist.
{
  "errors": [
    {
      "type": "parameter_missing",
      "message": "This parameter is required.",
      "parameter": "name"
    }
  ]
}

Pagination

All first-level collections of resources can be paginated. Collections are sorted by creation date, showing most recent objects first and limiting the results to 25 by default. To get adjust the number results you can use the limit parameter.

Given that it is assumed that new objects will be created, to keep pagination consistent you can obtain the next set of results from the last object id of the previous collection using the parameter starting_after. This includes the next set of results after (excluding) the passed id. This is also called vector pagination.

You can also achieve the opposite and retrieve all results up to the given id passing the ending_before.

Parameters
starting_after
string
Display results listed after (older) than the given id.
ending_before
string
Display results listed before (more recent) than the given id.
limit
integer
Limit how many results to show. Default is 25. Maximum is 100. 
curl -G https://api.hellotext.com/v1/profiles \
  -d starting_after="BvYeyVYz" \
  -d limit=10 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

Profiles

Customers are represented as customer profiles. Each individual customer represents a unique profile object that unifies all its characteristics and history of interactions with the business.

Profiles accept any number of properties like phone numbers, emails, geo-localized addresses, personal attributes as birthday, gender or any other customized one.

  • 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

The profile object

Attributes
id
String
Unique identifier of the object.
type
Type
Type of object. This is always profile.
blocked
Boolean
Has this profile been blocked or not. It is true or false
created_at
Epoch
Date of creation of the object.
emails
array
A collection of all the verified or unverified emails on this profile set as properties of kind email.
first_name
String
First name of the customer represented in the profile.
last_name
String
Last name of the customer represented in the profile.
lists
array
A collection of all the lists this profile is part of. Show child attributes
phones
array
A collection of all the verified or unverified phone numbers on this profile set as properties of kind phone, listed in e164 format.
properties
array
Array of hashes representing properties object of the profile. For example phone numbers, Mercado Libre properties. Show child attributes
state
Enum
The current state of the profile that indicates if the profile is explicitly subscribed to receive promotional content or does not want to receive any promotional communication.
Possible enum values
unconfirmed Default
subscribed
unsubscribed
verified_emails
array
A collection of all the verified emails of the profile.
verified_phones
array
A collection of all the verified phone numbers of the profile. 
{
  "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"
  ]
}

Create a profile

Creates a new profile.

Parameters
address
hash
Set the address for the default address property. You can pass an address object, or optionally provide a string as address[suggest]. When providing the suggestion string, we will deconstruct the string and construct an address object from it.
address[name]
String
Set the address for the address property with the name declared inside its brackets. For example address[work]= will set the address for the address property with name work. The property will be created for the current profile automatically if it does not exist already.
email
String
Set the email address for the default email property.
email[name]
String
Set the email address for the email property with the name declared inside its brackets. For example email[work]= will set the email for the email property with name work. The property will be created for the current profile automatically if it does not exist already.
first_name
String
The first name of the profile
last_name
String
The last name of the profile
lists
array
A collection of list names that this profile will be added to. New lists will be created if a list does not exist.
phone
String
Set the phone number for the default phone property. Expects a number in e164 format or otherwise a number in local format that will be converted to e164 using the business country for its country prefix.
phone[name]
String
Set the phone number for the phone property with the name declared inside its brackets. For example phone[work]= will set the phone for the phone property with name work. The property will be created for the current profile automatically if it does not exist already.
property[name]
String
Set a property value by passing the property's name, for example property[Active]=true. If the property does not have a name, it's possible to target it by it's kind, i.e property[gender]=male.
property_by_id[id]
String
Set a property value by passing the id of the property, for example property_by_id[gVlpOkwJ]=MyValue.
subscribe
Boolean
Set to true to subscribe the customer on profile creation. Typically this is used when already received explicit consent from the customer to receive promotional communications of your brand. The default value is false, meaning that new profiles do not become subscribed automatically. 
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"
}

Retrieve a profile

Retrieves an existing profile.

 
curl -G https://api.hellotext.com/v1/profiles/MzYwlE50 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

Update a profile

Updates the specified profile with the provided information.

Parameters
address
hash
Set the address for the default address property. You can pass an address object, or optionally provide a string as address[suggest]. When providing the suggestion string, we will deconstruct the string and construct an address object from it. Providing an empty value removes the default address from the profile. For example, address='' or address={}.
address[id]
String
Set an address property value by passing the id of the property, for example address[gVlpOkwJ]=MyValue. Passing an empty value will remove the address from the profile. For example, address[gVlpOkwJ]='' will remove the address with the given id.
address[name]
String
Set the address for the address property with the name declared inside its brackets. For example address[work]= will set the address for the address property with name work. The property will be created for the current profile automatically if it does not exist already. Passing an empty value will remove the address from the profile. For example, address[work]='' will remove the address work of the profile.
email
String
Set the email address for the default email property. Passing an empty value will remove the default email, for example email='' will remove the default email. If the Profile has other emails, the second email will be marked as the new default.
email[id]
String
Set an email property value by passing the id of the property, for example email[gVlpOkwJ]=will.e@acme.com. Passing an empty value will remove the email from the profile. For example, email[gVlpOkwJ]='' will remove the email with the given id.
email[name]
String
Set the email address for the email property with the name declared inside its brackets. For example email[work]= will set the email for the email property with name work. The property will be created for the current profile automatically if it does not exist already. Passing an empty value removes the email from the profile. For example, email[work]='' will remove the email work of the profile.
first_name
String
The first name of the profile
last_name
String
The last name of the profile
lists
array
A collection of all list names that this profile will be added to. Passing an empty array [] will remove the profile from every list.
new_address
hash
New default profile address. If present, it will replace the default address and become the new default. Without removing the old default address.
new_email
String
New default profile email. If present, it will replace the default email and become the new default. Without removing the old default email.
new_phone
String
New default profile phone. If present, it will replace the default phone number and become the new default. Without removing the old default number.
phone
String
Set the phone number for the default phone property. Expects a number in e164 format or otherwise a number in local format that will be converted to e164 using the business country for its country prefix. Passing an empty value will remove the default phone from the profile. For example, phone='' will remove the default phone of the Profile. If the profile has any other phone numbers, the second phone number is marked as the new default.
phone[id]
String
Set a phone property value by passing the id of the property, for example phone[gVlpOkwJ]=099888888. Passing an empty value will remove the phone from the profile. For example, phone[gVlpOkwJ]='' will remove the phone with the given id.
phone[name]
String
Set the phone number for the phone property with the name declared inside its brackets. For example phone[work]= will set the phone for the phone property with name work. The property will be created for the current profile automatically if it does not exist already. Passing an empty value will remove the phone from the profile if it exists. For example, phone[work]='' will remove the phone work of the profile.
property[name]
String
Set a property value by passing the property's name, for example property[Active]=true. If the property does not have a name, it's possible to target it by it's kind, i.e property[gender]=male.
property_by_id[id]
String
Set a property value by passing the id of the property, for example property_by_id[gVlpOkwJ]=MyValue. 
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
}

Delete a profile

Clears the specified profile. Clearing a profile means that all of it's properties will be removed. The associated conversations will be preserved. You can restore the profile once more through the dashboard or the API by changing the subscription state of the profile to subscribed.

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

List all profiles

Lists existing profiles sorting by most recent ones. Pagination parameters are available in lists.

Parameters
email
String
Limit result to profiles who have the specified email.
ending_before
String
Display results listed before (more recent) than the given id.
first_name
String
Limit results to profiles who have the specified first name.
last_name
String
Limit results to profiles who have the specified last name.
limit
integer
Limit how many results to show. Default is 25. Maximum is 100.
order
Enum
The order to sort the profiles. If an invalid value is specified, the default order is used.
Possible enum values
activity Default

Sort by the last activity date of the profile. Profiles with more recent activity will appear first.

alphabetically

Sort by last_name, first_name.

created_at

Sort by the creation date of the profile.

phone
String
Limit result to profiles who have the specified phone.
property[name]
String
Limit results to profiles who have the specified property value
starting_after
String
Display results listed after (older) than the given id. 
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"
      ]
    },
    "{...}",
    "{...}"
  ]
}

Subscribe a profile

Mark a profile as subscribed to receive promotional communications from your brand.

 
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"
  ]
}

Unsubscribe a profile

Unsubscribe a profile from receiving future promotional communications from your brand.

 
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"
  ]
}

Verify a profile's contactable

Verify a profile's contactable to ensure that the contactable has been verified to avoid impersonation. 

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
}

Unverify a profile's contactable

 
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
}

Properties

Properties are the attributes of profiles such as phone, email, company, gender, birthday and address.

You can create custom properties for any business specific need by simply choosing its property kind and an optional name. Each property kind expects a different structure for its value. For more information see the detailed breakdown below.

Once new properties are defined, they became immediately available on all new and existing profiles.

phone, email, mercadolibre properties are grouped together and shown before all other properties, in mentioned order. Thus, their position reflects only the ordering inside their own kind.

  • POST

    v1/properties

  • GET

    v1/properties/:id

  • PATCH

    v1/properties/:id

  • DELETE

    v1/properties/:id

  • GET

    v1/properties

The property object

Attributes
id
String
Unique identifier of the object.
type
Type
Type of object. This is always property.
created_at
Epoch
Date of creation of the object.
name
String
Optional name of the property. Duplicate names are not allowed
position
integer
Numeric position of the property in relation to others for sorting.
profile
profile
Unique identifier of the profile that this property belong to.
unique
Boolean
Is the property unique or not. Defaults to false. Property uniqueness determines whether multiple profiles can have the same value. Unique properties ensure that no two profiles have the same value. This is useful in cases where you want a single profile to have a specific value at a moment in time.
Aside from the below kinds, all other kinds can be configured as unique, updates to these properties targeting the unique attribute are ignored.
Cannot be unique
birthday
checkbox
date
gender
list
tags 
{
  "id": "OBYBnY69",
  "type": "property",
  "created_at": 1665684173,
  "kind": "text",
  "name": "My Property",
  "position": 8,
  "profile": null,
  "unique": false
}

Property kinds

Properties have different formats for their values depending on their kind.

Each kind of property expects a specific format as its value. Please refer to the description of each one below.

Properties values are always set from the profile object.

The address property

Represents an address associated to a profile. It can help to keep track of customer's addresses. Using this property makes it easier to target customers in specific regions, streets or countries.

Attributes
id
String
Identifier of the property object.
kind
String
The format of the property, this is always address.
value
hash
An object that contains the address information. Show child attributes 
{
  "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"
  }
}

The birthday property

The birthday property is based on the date property and it inherits its structure. It has a special birthday kind as it is specifically implemented to help keep track of customer birthdays. Using this property makes it easier to target customers by age or day of month when using Segments or Journeys.

Attributes
id
String
Identifier of the property object.
kind
String
The format of the property, this is always birthday.
value
hash
This hash represents a date. It is possible to partially complete with the information at hand. For example, you can only enter the year of birth or the day and month. Show child attributes 
{
  "id": "MQNKalb7",
  "kind": "birthday",
  "name": null,
  "value": {
    "day": 3,
    "month": 11,
    "year": 1985
  }
}

The checkbox property

Attributes
id
String
Identifier of the property object.
kind
String
The format of the property, this is always checkbox.
value
Boolean
Expects either true or false. Defaults to false. 
{
  "id": "MQNKalb7",
  "kind": "checkbox",
  "name": null,
  "value": false
}

The company property

Attributes
id
String
Identifier of the property object.
kind
String
The format of the property, this is always company.
value
String
Represents the name of a company. Can be used to store the name of the company the profile is associated with. 
{
  "id": "MQNKalb7",
  "kind": "company",
  "name": null,
  "value": "ACME Corporation"
}

The date property

Attributes
id
String
Identifier of the property object.
kind
String
The format of the property, this is always date.
value
hash
This hash represents a date. It is possible to partially complete with the information at hand. For example, you can only enter the year of birth or the day and month. Show child attributes 
{
  "id": "MQNKalb7",
  "kind": "date",
  "name": null,
  "value": {
    "day": 3,
    "month": 11,
    "year": 1985
  }
}

The email property

Attributes
id
String
Identifier of the property object.
kind
String
The format of the property, this is always email.
value
String
Represents an email address. Can be used to store the email address of the profile. 
{
  "id": "MQNKalb7",
  "kind": "email",
  "name": null,
  "value": "will.e@acme.com",
  "verified": true
}

The gender property

Attributes
id
String
Identifier of the property object.
kind
String
The format of the property, this is always gender.
value
String
Value that represents the gender of the profile. Use male for male and female for female. Use any other value to represent other genders. 
{
  "id": "MQNKalb7",
  "kind": "gender",
  "name": null,
  "value": "male"
}

The mercadolibre property

Attributes
id
String
Identifier of the property object.
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"
}

The number property

Attributes
id
String
Identifier of the property object.
kind
String
The format of the property, this is always number.
value
float
Represents a number. Can be used to store any numeric value. 
{
  "id": "MQNKalb7",
  "kind": "number",
  "name": null,
  "value": 29.99
}

The phone property

Attributes
id
String
Identifier of the property object.
kind
String
The format of the property, this is always phone.
value
String
Represents a phone number. Can be used to store the phone number of the profile. 
{
  "id": "MQNKalb7",
  "kind": "phone",
  "name": null,
  "value": "+59898000001",
  "verified": true
}

The tags property

Attributes
id
String
Identifier of the property object.
kind
String
The format of the property. This is always tags.
value
array
Represents a collection of tags. 
{
  "id": "MQNKalb7",
  "kind": "tags",
  "name": null,
  "value": [
    "tag1",
    "tag2"
  ]
}

The text property

Attributes
id
String
Identifier of the property object.
kind
String
The format of the property, this is always text.
value
String
Represents any specified text. Can be used for notes about the profile or to store any business specific metadata. 
{
  "id": "MQNKalb7",
  "kind": "text",
  "name": null,
  "value": "Long lasting customer"
}

The url property

Attributes
id
String
Identifier of the property object.
kind
String
The format of the property, this is always url.
value
String
Represents a URL. Can be used to store a link to a website or any other web resource. 
{
  "id": "MQNKalb7",
  "kind": "url",
  "name": null,
  "value": "https://www.hellotext.com"
}

Create a property

Creates a new property.

Parameters
kind
Enum
Required
The format of the property.
Possible enum values
address
email
phone
checkbox
date
number
tags
text
url
name
String
The name of the property. Certain restrictions apply to the name of the property when set:
  • - Name cannot be duplicate.
  • - Name cannot start with a number. For example, 1st-name is invalid.
  • - Name cannot contain curly brackets. For example, {name} is invalid.
position
integer
Numeric position of the property in relation to others for sorting. New properties get the last position number if not specified. If specified, existing properties will update their positions accordingly. Accepted values must be greater than zero
profile
profile
Unique identifier of the profile that this property belong to. If specified, the property becomes only available for the specified profile and will not be visible to others. It can only be assigned to address, email or phone. Required when the property kind is address, email or phone.
unique
Boolean
Is the property unique or not. Defaults to false. Property uniqueness determines whether multiple profiles can have the same value. Unique properties ensure that no two profiles have the same value. This is useful in cases where you want a single profile to have a specific value at a moment in time. 
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
}

Retrieve a property

Retrieves an existing property.

 
curl -G https://api.hellotext.com/v1/properties/OBYBnY69 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

Update a property

Updates the specified property with the provided information.

Parameters
name
String
The name of the property. Certain restrictions apply to the name of the property when set:
  • - Name cannot be duplicate.
  • - Name cannot start with a number. For example, 1st-name is invalid.
  • - Name cannot contain curly brackets. For example, {name} is invalid.
position
integer
Numeric position of the property in relation to others for sorting. New properties get the last position number if not specified. If specified, existing properties will update their positions accordingly. Accepted values must be greater than zero. Providing an empty value position='' moves the property to the bottom of the properties list.
unique
Boolean
Changes the uniqueness of the property. Converting a non unique property to unique will fail if multiple profiles have the same value. In these cases you need to resolve the conflict before continuing to make the property unique. 
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
}

Delete a property

Permanently deletes the specified property.

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

List all properties

Lists existing properties sorting by most recent ones. Pagination parameters are available in lists.

Parameters
ending_before
String
Display results listed before (more recent) than the given id.
limit
integer
Limit how many results to show. Default is 25. Maximum is 100.
profile
profile
Unique identifier of the profile.
starting_after
String
Display results listed after (older) than the given id. 
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
    },
    "{...}",
    "{...}"
  ]
}

Lists

Lists act as logical grouping of profiles.

  • POST

    v1/lists

  • GET

    v1/lists/:id

  • PATCH

    v1/lists/:id

  • DELETE

    v1/lists/:id

  • GET

    v1/lists

The list object

Attributes
id
String
Unique identifier of the object.
type
Type
Type of object. This is always list.
created_at
Epoch
Date of creation of the object.
name
String
Name of the list, case-sensitive. Duplicate names are not allowed 
{
  "id": "zN4Xx4Km",
  "type": "list",
  "name": "Greens",
  "created_at": 1665684173
}

Create a list

Creates a new list.

Parameters
name
String
Required
Name of the list, case-insensitive. Duplicate names are not allowed. 
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
}

Retrieve a list

Retrieves an existing list. You can fetch an existing List by it's id or name attributes.

 
curl -G https://api.hellotext.com/v1/lists/zN4Xx4Km 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

Update a list

Updates an existing list. You can update a List by it's id or name attributes.

Parameters
name
String
Required
Name of the list, case-insensitive. Duplicate names are not allowed. 
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
}

Delete a list

Deletes an existing list. You can delete a List by it's id or name attributes.

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

List all lists

Lists existing lists sorting by most recent ones. Pagination parameters are available in lists.

Parameters
ending_before
String
Display results listed before (more recent) than the given id.
limit
integer
Limit how many results to show. Default is 25. Maximum is 100.
search
String
Display lists whose name start with the provided value
starting_after
String
Display results listed after (older) than the given id. 
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
    },
    "{...}",
    "{...}"
  ]
}

Add Profile to a List

Adds a profile to a list if the profile is not already in the list. You can specify the list by its id or name attributes.

 
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"
  ]
}

Remove Profile from a List

Removes a profile from a list if the profile is a member in the list. You can specify the list by its id or name attributes.

 
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"
  ]
}

The Template Object

The template object represents a reusable message that can be quickly reused on the Compose.

With templates, you create your message once and reuse it as many times as you want. You don't need to rewrite the same message multiple times.

You can create a template for a message that you send frequently, such as a weekly newsletter, a monthly report, or a reminder.

Templates are composed of components, which represent different parts of the message. Some technologies support template components such as WhatsApp, others such as SMS do not. If a template is sent via SMS, even if it contains other components, only the body component is used.

Templates are made up of four primary components which you define when you create a template: header, body, footer, and buttons. The components you choose for each of your templates should be based on your business needs. The only required component is the body component. In the aforementioned paragraph, we mentioned that if a template is sent via SMS, only the body component is used.

The optional header component supports three types, address, attachment and text. Address headers are shown as a map preview that opens the customer's default map app on their device. Attachment headers are shown as a preview of the attachment. Text headers are shown on WhatsApp as a header above the message, and they are limited to 60 characters

The required body component is the actual message content. This is the main part of the message that you want to send. It supports parameters, which are placeholders that you can use to personalize the message for each recipient.

The optional footer component is shown at the bottom of the message. It can be used to provide additional information or a call to action. We recommend to use the footer component to provide a way for the recipient to opt-out of receiving messages. Such as "Send STOP to unsubscribe". The footer is limited to 160 characters.

The optional buttons component is shown at the bottom of the message. It can be used to provide a way for the recipient to interact with the message. Templates support up-to 10 buttons in total. Each type has a certain limit as well, read below for more information.

  • POST

    v1/templates

  • GET

    v1/templates/:id

  • PATCH

    v1/templates/:id

  • DELETE

    v1/templates/:id

  • GET

    v1/templates

The Template Object

Attributes
id
String
Unique identifier of the object.
type
Type
Type of object. This is always template.
body
String
The body of the template.
buttons
array
The buttons associated with the template. They are ordered based on the index or the position parameter you specified when creating or updating the template. Show child attributes
created_at
Epoch
Date of creation of the object.
footer
String
The footer of the template.
header
hash
The header component of the template. Show child attributes
name
String
The name of the template.
state
Enum
The state of the template.
Possible enum values
approved

The template is approved and can be used to send messages. Templates that target sms or any(when the business has not integrated a WhatsApp account) are automatically set to approved state.

pending

The template is pending approval. Templates that target whatsapp or any(when the business has integrated a WhatsApp account) are automatically set to pending state. Once the WhatsApp template is approved, it is set to approved state.

rejected

The template is rejected and cannot be used to send messages. Update the template to resubmit for approval.

technology
Enum
The target platform intended for the template.
Possible enum values
any Default

An alias for all connected platforms at the time of the inception of the template, SMS, WhatsApp, Instagram, etc. If at the time of the inception of the template the business has not integrated WhatsApp, and integrated WhatsApp at a later date, a WhatsApp template is automatically created.

sms

This template is intended for SMS messages. The template cannot be used on WhatsApp.

whatsapp

This template is intended for WhatsApp messages. The template cannot be used on SMS. 

{
  "id": "MzYwlE50",
  "type": "template",
  "body": "Hello, how can I help you today?",
  "buttons": [
    {
      "type": "copy",
      "copy": "123456",
      "text": "Copy text"
    },
    {
      "type": "url",
      "text": "Visit our website",
      "url": "https://example.com"
    },
    {
      "type": "phone",
      "phone": "+1234567890",
      "text": "Call us"
    },
    {
      "type": "quick_reply",
      "text": "Button text"
    },
    {
      "type": "quick_reply",
      "text": "Button text"
    },
    {
      "type": "quick_reply",
      "text": "Button text"
    }
  ],
  "created_at": 1665684173,
  "footer": "Send STOP to unsubscribe",
  "state": "approved",
  "header": {
    "type": "text",
    "text": "Welcome to our store"
  }
}

Header types

The header component is optional and supports three types, address, attachment and text. Text headers are shown on WhatsApp as a header above the message, and they are limited to 60 characters. Attachment headers are shown as a preview of the attachment.

The address header type is used to display a clickable map that opens the customer's default map application. This is useful for providing the recipient with a location or directions to a location, like a store or office.

The text header type is used to display a text header above the message. The text header is limited to 60 characters.

The attachment header type is used to display a preview of an attachment. The attachment is downloaded and stored on Hellotext's servers. The attachment is shown as a preview of the attachment. The attachment is not shown on SMS messages.

Notes about attachments

  • Each platform has different limitations on the size and type of attachments that can be sent. Below is a list of supported file types and the maximum file size for each platform.
  • While Hellotext automatically converts the attachment to a format that is supported by the platform, it's best for the attachment to be in the supported formats to avoid data-loss during conversion. Make sure the file size is within the platform's limitations highlighted below.
Whatsapp Attachment Limitations
Media Type Supported Formats Maximum Size

Image

jpeg, png

5MB

Video

3gp, mp4

25MB

Document

pdf, doc, docx, ppt, pptx, xls, xlsx

100MB
Instagram Attachment Limitations
Media Type Supported Formats Maximum Size

Image

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

Template body

The body component is the only required component of a template. This is the main part of the message that you want to send. It supports parameters, which are placeholders that you can use to personalize the message for each recipient.

Parameters are dynamic tags that you can use to personalize the message for each recipient. When you send a template message, you can replace the parameters with the actual values.

There are two categories of parameters you can use in a template, these are tags. and shortlinks.

Parameters are embedded in the body of the template, they are enclosed inside a curly brace {}. When you send a template message, you can replace the parameters with the actual values.

Property tags

Property tags are used to personalize the message with the recipient's information. For example, you can use the recipient's name, email address, or phone number. Additionally, you can use any custom properties that you have defined.

See the Properties for more information on how to create a property. You can also create properties in the dashboard.

Learn more about tags and how they work, and the rules applied to them.

Properties

{name}

Target's the profile's first name.

{full_name}

Target's the profile's full name.

{last_name}

Target's the profile's last name.

{birthday}

Target's the profile's birthday.

{email}

Target's the profile's default email address.

{phone}

Target's the profile's default phone number.

{address}

Target's the profile's default address.

{company}

Target's the profile's company property.

In addition to the above tags, you are free to target any custom property you have defined.

The rules are simple, you write the name of the property inside curly braces {}. Although the casing is insensitive, it is recommended to use the same casing as the property name. 

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

Shortlink tags

ShortLinks is link-shortening service operated by Hellotext that allows you to shorten URLs and redirect them to a specific URL.

ShortLink redirects attach a hello_session identifier to the URL, then you can leverage Hellotext.js to track events and user's interaction with the ShortLink back to Hellotext. These events appear in the Activity Trail of that profile.

Using ShortLinks in templates is straightforward, the same rules apply as with property tags. There are two categories of ShortLinks, dynamic and static.

Static ShortLinks

Static ShortLinks are short links that are the same for all recipients. This is useful if you want to track the number of clicks on a specific URL.

The format is {shortlink:url}, where url is the URL you want to shorten. For example, {shortlink:https://hellotext.com} generates a ShortLink that redirects to https://hellotext.com while attaching a hello_session identifier.

Dynamic ShortLinks

Dynamic ShortLinks are short links that are personalized for each recipient. This is useful if each message you send to a customer has a unique URL specific to that customer.

The format is {shortlink:name}, where name is the variable name you want to use.

For example, if you want to send a message to a customer with a unique URL to their account page, you can use {shortlink:account} as the ShortLink. When you send the message, you replace the ShortLink with the actual URL. 

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

Button types

Buttons are optional interactive components that perform specific actions when tapped. Templates can have a mixture of up to 10 button components total, although there are limits to individual buttons of the same type as well as combination limits. These limits are described below.

Buttons can include a position argument between 0 and 9 to indicate the order of the button, an automatic position is selected based on the index of the button when creating or updating template buttons.

URL buttons

URL buttons load the specified URL in the device's default web browser when tapped by the app user.

Templates are limited to 2 URL buttons.

Attributes
type
Type
Type of object. This is always url.
text
String
The text to display on the button. 25 characters maximum.
url
URL
The URL to load when the button is tapped. 2000 characters maximum. 
{
  "type": "url",
  "text": "Visit our website",
  "url": "https://example.com"
}

Phone buttons

Phone number buttons call the specified business phone number when tapped by the app user.

Templates are limited to 1 phone number button.

Attributes
type
Type
Type of object. This is always phone.
phone
String
The phone number to call when the button is tapped. Maximum 20 characters.
text
String
The text to display on the button. 25 characters maximum. 
{
  "type": "phone",
  "phone": "+1234567890",
  "text": "Call us"
}

Quick Reply buttons

Quick reply buttons are custom text-only buttons that immediately message you with the specified text string when tapped by the app user. A common use case-case is a button that allows your customer to easily opt-out of any marketing messages.

Templates are limited to 10 quick reply buttons.

Attributes
type
Type
Type of object. This is always quick_reply.
text
String
The text to display on the button. 25 characters maximum. 
{
  "type": "quick_reply",
  "text": "Button text"
}

Copy buttons

Copy code buttons copy a text string (defined when the template is sent in a template message) to the device's clipboard when tapped by the app user.

Templates are limited to 1 copy code button.

Attributes
type
Type
Type of object. This is always copy.
copy
String
The text to copy to the clipboard when the button is tapped.
text
String
The text to display on the button. 25 characters maximum. 
{
  "type": "copy",
  "copy": "123456",
  "text": "Copy text"
}

Create a Template

Creates a new template object.

Notes

  • WhatsApp templates are limited to 1024 characters. WhatsApp templates can only be created when the business has an integrated WhatsApp Business account that has not been disabled, restricted or banned.
  • SMS templates are limited to 160 characters.
  • SMS template do not support header, footer, or buttons components. Attempting to assign these components returns an invalid error.
Parameters
body
String
Required
The body of the template.
buttons
array
The buttons associated with the template. Maximum 10 buttons in total. Refer to the button types for more information.

An automatic position is selected based on the index of the button when no position is specified. You may include an optional position argument between 1 and 10 to indicate the order of the button. Show child attributes
footer
String
The footer of the template.
header
hash
The header component of the template. Show child attributes
name
String
Required
The name of the template. Case sensitive, duplicate names are not allowed.
technology
Enum
The target platform intended for the template. WhatsApp can only be set when the business has integrated a WhatsApp account. If you try to create a WhatsApp template but you have not integrated WhatsApp, an error is returned.

any - is an alias for all connected platforms, SMS, WhatsApp, Instagram, etc. When the business has integrated a WhatsApp account, any will create the template to target both WhatsApp and SMS.

sms - This template is intended for SMS messages. The template cannot be used on WhatsApp.

whatsapp - This template is intended for WhatsApp messages. The template cannot be used on SMS. Templates that target WhatsApp are automatically set to pending state. Once the WhatsApp template is approved, it is set to approved state.
Possible enum values
any Default
sms
whatsapp 
curl -X POST https://api.hellotext.com/v1/templates 
 -d body="Hello {name}, how can we assist you today?" 
 -d footer="One of our agents will be with you shortly." 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "id": "MzYwlE50",
  "type": "template",
  "body": "Hello, how can I help you today?",
  "buttons": [
    {
      "type": "copy",
      "copy": "123456",
      "text": "Copy text"
    },
    {
      "type": "url",
      "text": "Visit our website",
      "url": "https://example.com"
    },
    {
      "type": "phone",
      "phone": "+1234567890",
      "text": "Call us"
    },
    {
      "type": "quick_reply",
      "text": "Button text"
    },
    {
      "type": "quick_reply",
      "text": "Button text"
    },
    {
      "type": "quick_reply",
      "text": "Button text"
    }
  ],
  "created_at": 1665684173,
  "footer": "Send STOP to unsubscribe",
  "state": "approved",
  "header": {
    "type": "text",
    "text": "Welcome to our store"
  }
}

Retrieve a Template

Retrieves a template object. 

curl -G https://api.hellotext.com/v1/templates/xJEOaPdk 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "id": "xJEOaPdk",
  "type": "template",
  "body": "Hello, how can I help you today?",
  "buttons": [
    {
      "type": "copy",
      "copy": "123456",
      "text": "Copy text"
    },
    {
      "type": "url",
      "text": "Visit our website",
      "url": "https://example.com"
    },
    {
      "type": "phone",
      "phone": "+1234567890",
      "text": "Call us"
    },
    {
      "type": "quick_reply",
      "text": "Button text"
    },
    {
      "type": "quick_reply",
      "text": "Button text"
    },
    {
      "type": "quick_reply",
      "text": "Button text"
    }
  ],
  "created_at": 1665684173,
  "footer": "Send STOP to unsubscribe",
  "state": "approved",
  "header": {
    "type": "text",
    "text": "Welcome to our store"
  }
}

Update a Template

Updates a template object.

Notes about WhatsApp templates

  • Templates that target WhatsApp are limited to 1 updates per day. This means that if you update a WhatsApp template, you cannot update it again until 24 hours have passed. Attempting to update a WhatsApp template more than once in a day will be rejected with an invalid error.
  • In addition, a WhatsApp template can only be edited when it's either approved, rejected or paused. Attempting to update a WhatsApp template that is in the pending state will be rejected with an invalid error.
  • Names cannot be changed. If you supply name in the parameters, it is ignored.
Parameters
body
String
The body of the template.
buttons
array
The buttons associated with the template. An automatic position is selected based on the index of the button. You may pass an empty array [] to remove all of the buttons of the template. Show child attributes
footer
String
The footer of the template.
header
hash
The header component of the template. You can pass null or {} to remove the header. If the header's type was an attachment, the attachment is deleted from Hellotext's servers. Show child attributes
name
String
The name of the template. Case sensitive, duplicate names are not allowed. If the template targets WhatsApp, updates to the name are ignored. This is because WhatsApp template names cannot be changed once they are created.
technology
Enum
The target platform intended for the template. Once changed, it becomes unusable on the previous platform. For example, changing the technology from whatsapp to sms will make the template unusable on WhatsApp, this means that you will not be able to send messages using this template on WhatsApp.

WhatsApp can only be set when the business has integrated a WhatsApp account. If you try to create a WhatsApp template but you have not integrated WhatsApp, an error is returned.
Possible enum values
any Default
sms
whatsapp 
curl -X PATCH https://api.hellotext.com/v1/templates/xJEOaPdk 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "id": "xJEOaPdk",
  "type": "template",
  "body": "Hello, how can I help you today?",
  "buttons": [
    {
      "type": "copy",
      "copy": "123456",
      "text": "Copy text"
    },
    {
      "type": "url",
      "text": "Visit our website",
      "url": "https://example.com"
    },
    {
      "type": "phone",
      "phone": "+1234567890",
      "text": "Call us"
    },
    {
      "type": "quick_reply",
      "text": "Button text"
    },
    {
      "type": "quick_reply",
      "text": "Button text"
    },
    {
      "type": "quick_reply",
      "text": "Button text"
    }
  ],
  "created_at": 1665684173,
  "footer": "Send STOP to unsubscribe",
  "state": "approved",
  "header": {
    "type": "text",
    "text": "Welcome to our store"
  }
}

Destroy a Template

Deletes a template object.

The template object is kept for internal reference as there may have been messages that relied on it before deletion. However, the template becomes inaccessible and cannot be used to send new messages. You can create a new template with the same name.

Notes about WhatsApp templates

  • Names of approved template that have been deleted cannot be reused for 30 days.
  • You can only create a new template with the same name when the deleted template did not target WhatsApp. 
curl -X DELETE https://api.hellotext.com/v1/templates/xJEOaPdk 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "id": "MzYwlE50",
  "type": "template",
  "deleted": true
}

List all Templates

Lists all template objects. Supports pagination.

Parameters
ending_before
String
Display results listed before (more recent) than the given id.
limit
integer
Limit how many results to show. Default is 25. Maximum is 100.
starting_after
String
Display results listed after (older) than the given id. 
curl -G https://api.hellotext.com/v1/templates 
 -d limit=5 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "templates": [
    {
      "id": "MzYwlE50",
      "type": "template",
      "body": "Hello, how can I help you today?",
      "buttons": [
        {
          "type": "copy",
          "copy": "123456",
          "text": "Copy text"
        },
        {
          "type": "url",
          "text": "Visit our website",
          "url": "https://example.com"
        },
        {
          "type": "phone",
          "phone": "+1234567890",
          "text": "Call us"
        },
        {
          "type": "quick_reply",
          "text": "Button text"
        },
        {
          "type": "quick_reply",
          "text": "Button text"
        },
        {
          "type": "quick_reply",
          "text": "Button text"
        }
      ],
      "created_at": 1665684173,
      "footer": "Send STOP to unsubscribe",
      "state": "approved",
      "header": {
        "type": "text",
        "text": "Welcome to our store"
      }
    },
    "{...}",
    "{...}"
  ]
}

The Message Object

A message is a communication between you and a profile. You can send text messages, or reuse an existing Template.

  • POST

    v1/messages

  • GET

    v1/messages/:id

  • GET

    v1/messages

The Message Object

Attributes
id
String
Unique identifier of the object.
type
Type
Type of object. This is always message.
attachments
array
A list of attachment URLs associated with the message.
body
String
The content of the message. Optional when using a template, required when no template is specified.
created_at
Epoch
Date of creation of the object.
delivered_at
Epoch
The timestamp of when the message was delivered.
destination
String
The identifier of the profile that will receive the message. This can be a phone number, Instagram username, or MercadoLibre user ID.
failed_at
Epoch
The timestamp of when the message failed to be delivered.
origin
String
The identifier of the channel used to send the message.
profile
profile
The id of the profile to send the message to.
received_at
Epoch
The timestamp of when the message was received by the profile. This can be used to determine if the message was from the profile or from the business.
routed_at
Epoch
The timestamp of when the message was routed to the external gateway.
state
Enum
The current state of the message.
Possible enum values
delivered

The message has been delivered successfully. Check delivered_at for the exact time.

failed

The message has failed to be delivered.

pending Default

The message has been created successfully and is pending for delivery.

received

This message was sent by the profile to the business.

routed

The message has been routed to the external gateway. Once the carrier reports back, the message either is delivered or failed.

technology
Enum
The technology used to deliver the message.
Possible enum values
instagram

The message was delivered with Instagram.

mercadolibre

The message was delivered with MercadoLibre.

sms

The message was delivered with SMS.

whatsapp

The message was delivered with WhatsApp.

template
template
The id of the template used to send the message. 
{
  "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"
}

Template Messages

Learn how to send messages using a template. Make sure you have read about Templates and understand the components and how to use them before sending a message.

Dynamic Shortlinks in Template Messages

You can reserve placement for dynamic shortlinks in the template's body when you create it. Refer to the ShortLink Types documentation for more information about the types of shortlinks and how to create them.

The following sections assumes you have already created a template with dynamic shortlinks and have a firm understanding on how they work.

Each dynamic shortlink is a variable name that can be targeted and replaced with a specific URL when sending the message. Consider the template we want to use has three tags. A {name} property tag that is replaced by the profile's first name. And two dynamic short-links, {shortlink:appointment} and {shortlink:reschedule}.

To replace the shortlinks when sending the message, you provide each dynamic shortlinks' name with a URL via a shortlinks parameter on the template object.

If you see the Message Parameters we have when creating the message, you will see that in message.template.shortlinks we have a hash with the shortlink names and their respective URLs. Each provided URL is shortened and replaces the dynamic shortlink in the template's body, order does not matter as dynamic sections are replaced by their respective names. 

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

Send a Message

Send a free-form message or a template message to send to a profile.

Notes

  • WhatsApp messages are limited to 4096 characters. WhatsApp messages can only be sent when the business has an integrated WhatsApp Business account that has not been disabled, restricted or banned.
  • Instagram messages are limited to 1000 characters. Instagram messages can only be sent when the business has an integrated Instagram profile.
  • MercadoLibre messages are limited to 350 characters. MercadoLibre messages can only be sent when the business has an integrated MercadoLibre shop.
  • SMS messages are limited to 160 characters.
  • As a reminder, make sure to only send messages to users who have not opted-out of receiving messages from you. See the profile's subscription_state for more information.
  • When using a template that uses Dynamic ShortLinks, it is required to provide the shortlinks' URLs when creating the message failing to provide a URL for a dynamic short-link will result in errors being returned.

Notes about WhatsApp Messages

  • You can only send a free-form message to a profile if the profile has an open conversation window. Otherwise, you must use a template. This is called Customer Service Window.
  • Whenever a profile messages you through WhatsApp, a 24-hour timer called a customer service window starts (or refreshes if one has already been started).
  • When a customer service window is open between you and a user, you can send free-form messages to the user. If a window is not open between you and the user, you can only send template messages to the user, as template messages are the only type that can be sent outside of a customer service window.

Notes about attachments

  • Each platform has different limitations on the size and type of attachments that can be sent. Below is a list of supported file types and the maximum file size for each platform.
  • While Hellotext automatically converts the attachment to a format that is supported by the platform, it's best for the attachment to be in the supported formats to avoid data-loss during conversion. Make sure the file size is within the platform's limitations highlighted below.
Whatsapp Attachment Limitations
Media Type Supported Formats Maximum Size

Image

jpeg, png

5MB

Video

3gp, mp4

25MB

Document

pdf, doc, docx, ppt, pptx, xls, xlsx

100MB
Instagram Attachment Limitations
Media Type Supported Formats Maximum Size

Image

png, jpeg, gif

8MB

Video

mp4, ogg, avi, mov, webm

25MB
Parameters
attachments
array
A list of attachment URLs to send with the message. Make sure each URL is publicly accessible, the attachments are downloaded and stored on Hellotext's servers.
body
String
Required
The content of the message. Optional when using a template, required when no template is specified.
destination
String
The identifier of the profile's destination to send the message to. This can be a phone number, Instagram username, or MercadoLibre user ID.

Hellotext automatically selects a destination based on the configured origin and technology. Otherwise, you can specify the destination to send the message to a specific identifier of the profile.
origin
String
The identifier of the channel used to send the message. When this is empty, Hellotext will determine the best channel to use based on the profile's reachability and the business' configured channels.

For example, when sending a message to a profile, and you do not specify the origin, Hellotext will use a channel that the profile can be reached with. This means that, if the profile can be reached via WhatsApp, the message is sent via WhatsApp, and if the profile can be reached via SMS, the message is sent via SMS.
profile
profile
Required
The id of the profile to send the message to.
technology
Enum
Which technology to route the message through. When this is empty, Hellotext will determine the best technology to use based on the profile's reachability and the business' configured channels. Technologies have the following order of priority: WhatsApp, Instagram and SMS.

Keep in mind that integrations such as WhatsApp, Instagram or Mercadolibre require an active integration connected by the business. Attempting to send a message via a technology that's not available returns an invalid error.
Possible enum values
instagram
sms
whatsapp
template
hash
Either a string identifier of the template to use when sending the message, or a hash. When set, the body of the message is ignored and the template's body is used instead. Templates are reusable messages that can be used to send messages to profiles. When the template has dynamic shortlinks, you must provide the shortlinks' URLs when creating the message. Failing to provide a URL for a dynamic short-link will result in errors being returned. Show child attributes 
curl -X POST https://api.hellotext.com/v1/messages 
 -d origin="+14155552671" 
 -d profile="zGrDJ1Lb" 
 -d template="K75Vq1dL" 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "id": "zGrDJ1Lb",
  "type": "message",
  "attachments": [

  ],
  "body": "Hi John, how can we help you today?",
  "created_at": 1665684173,
  "delivered_at": null,
  "destination": "+14155552672",
  "failed_at": null,
  "origin": "+14155552671",
  "profile": "zGrDJ1Lb",
  "routed_at": null,
  "state": "pending",
  "technology": "whatsapp",
  "template": "K75Vq1dL"
}
curl -X POST https://api.hellotext.com/v1/messages 
 -d origin="+14155552671" 
 -d profile="zGrDJ1Lb" 
 -d body="To be or not to be, that is the question." 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "id": "zGrDJ1Lb",
  "type": "message",
  "attachments": [

  ],
  "body": "To be or not to be, that is the question.",
  "created_at": 1665684173,
  "delivered_at": null,
  "destination": "+14155552672",
  "failed_at": null,
  "origin": "+14155552671",
  "profile": "zGrDJ1Lb",
  "routed_at": null,
  "state": "pending",
  "technology": "whatsapp",
  "template": null
}

Retrieve a Message

Retrieve a message by its id. 

curl -G https://api.hellotext.com/v1/messages/APwbP54L 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

List all Messages

List all messages associated with the business.

Parameters
ending_before
String
Display results listed before (more recent) than the given id.
limit
integer
Limit how many results to show. Default is 25. Maximum is 100.
starting_after
String
Display results listed after (older) than the given id. 
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"
    },
    "{...}",
    "{...}"
  ]
}

Coupons

Import the coupons from your eCommerce that you would like to send on your promotional campaigns. You can measure the results of the different coupons.

  • POST

    v1/coupons

  • GET

    v1/coupons/:id

  • PATCH

    v1/coupons/:id

  • DELETE

    v1/coupons/:id

  • GET

    v1/coupons

The coupon object

Attributes
id
String
Unique identifier of the object.
type
Type
Type of object. This is always coupon.
code
String
Redeemable code of the coupon. This is the name of the coupon the customer sees, i.e. SALE.
created_at
Epoch
Date of creation of the object.
description
String
Description of the coupon. This is available as a tag to be used on messages.
destination_url
URL
URL that redeems the coupon.
reference
String
The coupon number or original identifier from the external source that created the coupon. 
{
  "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
}

Create a coupon

Creates a new coupon.

Parameters
code
String
Required
Redeemable code of the coupon. This is the name of the coupon the customer sees, i.e. SALE. Case-sensitive. Duplicate names are not allowed.
description
String
Required
Description of the coupon. This is available as a tag to be used on messages.
destination_url
URL
Required
URL that redeems the coupon.
reference
String
The coupon number or original identifier from the external source that created the coupon. 
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
}

Retrieve a coupon

Retrieves an existing coupon.

 
curl -G https://api.hellotext.com/v1/coupons/xJEOaPdk 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

Update a coupon

Updates the specified coupon with the provided information.

Parameters
code
String
Required
Redeemable code of the coupon. This is the name of the coupon the customer sees, i.e. SALE. Case-sensitive. Duplicate names are not allowed.
description
String
Required
Description of the coupon. This is available as a tag to be used on messages.
destination_url
URL
Required
URL that redeems the coupon.
reference
String
The coupon number or original identifier from the external source that created the coupon. 
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
}

Delete a coupon

Permanently deletes the specified coupon.

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

List all coupons

Lists existing coupons sorting by most recent ones. Pagination parameters are available in lists.

Parameters
ending_before
String
Display results listed before (more recent) than the given id.
limit
integer
Limit how many results to show. Default is 25. Maximum is 100.
starting_after
String
Display results listed after (older) than the given id. 
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
    },
    "{...}",
    "{...}"
  ]
}

Tracking

Tracking customers interactions unlock new marketing possibilities and give businesses a complete view of the history of each customer.

By tracking customer actions it is possible to build segmented audiences based on what they do and like and use this for highly precision marketing. Businesses can trigger automations based on customer activity and give their team a head start finding opportunities to actively engage with them to sell more.

A minimal setup to track a customer event is to set the action parameter to any of the built-in actions or a custom-defined action (see Actions) and the parameter profile that represents the customer profile or the session if tracking events from campaigns or journeys short links (see Sessions).

When providing both session and profile parameters, ensure that the session is assigned to the profile. Sessions assigned to a profile cannot be used to track events for another profile. If the session is not assigned to any profile, it will be automatically assigned to the profile you pass when tracking an event.

When providing a currency. The amount must be specified. If none are provided, the values will be inherited from the trackable if the object has the attributes.

 
  POST /v1/attribution/events

Track app events

Track important events performed by your customers when they interact with your app. Most common actions include tracking when an app is installed with action app.installed, removed with app.removed, or when a user spends a certain amount with app.spent.

When tracking events associated to sessions created after a campaign all attribution values including monetary values will be aggregated into the campaign reportings.

Parameters
action
enum
Required
The name of the action to track.
Possible enum values
app.installed
app.removed
app.spent
amount
float
Monetary amount that represents the revenue associated to this tracked event. Default value is null. Required if action=app.spent.
app
string
Required
Unique identifier of the app object associated to this event.
app_parameters
hash
A hash the can be passed instead of app parameter. The app will be created and have the event tracked for Show child attributes
currency
currency
Currency for the amount given in ISO 4217 format. Default value is always USD. Required if action=app.spent.
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
Required if session is not specified. Unique identifier of the profile object this event belongs to. If not explicitly specified, the profile identifier can be inherited when the session parameter is specified and the session is already associated to a profile or becomes later attached to one.
session
string
Required if profile is not specified. Identifier of the session object this event belongs to. Sessions are identifiers generated automatically from clicks by visitors on short links or from the Hellotext.js library when keeping track of anonymous visitors. It is a way to track events on the client-side without authenticating or disclosing the profile identifier allowing to associate it later to a profile securely on the server-side. More on Sessions.
tracked_at
epoch
Original date when the event happened. This is useful if you want to record an event that happened in the past. If no value is provided its value will be the same from created_at.
url
url
The url of the page this event occurred at. 
curl https://api.hellotext.com/v1/attribution/events \
  -d action="app.installed" \
  -d app=xnqJQ47v \
  -d session=2KAGgAgm \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "status": "received"
}

Track cart events

Track the events performed by customers when they add or remove items from their shopping cart. Or abandoning the cart

The monetary values associated to the cart items will be aggregated to the campaign reportings.

Parameters
action
enum
Required
A hash that represents the action object.
Possible enum values
cart.abandoned
cart.added
cart.removed
amount
float
Monetary amount that represents the revenue associated to this tracked event. Default value is null.
cart
string
The identifier of the cart object. Required when action is cart.abandoned.
currency
currency
Currency for the amount given in ISO 4217 format. Default value is always USD.
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.
products
string
A collection of products included in the cart. It can be a mix of product or product variant identifiers (id, reference or sku) and product_parameters and product_variant_parameters. Required when action is cart.added or cart.removed.

When Cart is not given, a Cart object will be created automatically and the products are added to it. When Cart is given, the products will be added to the Cart. And the products will be displayed in the Activity Trail of the Profile.

Make sure to set the reference or sku for the product or product variant to avoid creating duplicate products.
profile
string
Required if session is not specified. Unique identifier of the profile object this event belongs to. If not explicitly specified, the profile identifier can be inherited when the session parameter is specified and the session is already associated to a profile or becomes later attached to one.
session
string
Required if profile is not specified. Identifier of the session object this event belongs to. Sessions are identifiers generated automatically from clicks by visitors on short links or from the Hellotext.js library when keeping track of anonymous visitors. It is a way to track events on the client-side without authenticating or disclosing the profile identifier allowing to associate it later to a profile securely on the server-side. More on Sessions.
tracked_at
epoch
Original date when the event happened. This is useful if you want to record an event that happened in the past. If no value is provided its value will be the same from created_at.
url
url
The url of the page this event occurred at. 
curl https://api.hellotext.com/v1/attribution/events \
  -d action="cart.added" \
  -d app=xnqJQ47v \
  -d session=2KAGgAgm \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "status": "received"
}

Track coupon events

Track the events performed by your customers when they redeem coupons. Available value is coupon.redeemed for coupons redeemed.

The monetary values associated to the coupon redeem will be aggregated to the campaign reportings.

Parameters
action
enum
Required
The name of the action to track.
Possible enum values
coupon.redeemed
amount
float
Monetary amount that represents the revenue associated to this tracked event. Default value is null.
coupon
string
Required
Unique identifier of the coupon object associated to this event.
coupon_parameters
hash
A hash the can be passed instead of coupon parameter. The coupon will be created and have the event tracked for. Show child attributes
currency
currency
Currency for the amount given in ISO 4217 format. Default value is always USD.
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
Required if session is not specified. Unique identifier of the profile object this event belongs to. If not explicitly specified, the profile identifier can be inherited when the session parameter is specified and the session is already associated to a profile or becomes later attached to one.
session
string
Required if profile is not specified. Identifier of the session object this event belongs to. Sessions are identifiers generated automatically from clicks by visitors on short links or from the Hellotext.js library when keeping track of anonymous visitors. It is a way to track events on the client-side without authenticating or disclosing the profile identifier allowing to associate it later to a profile securely on the server-side. More on Sessions.
tracked_at
epoch
Original date when the event happened. This is useful if you want to record an event that happened in the past. If no value is provided its value will be the same from created_at.
url
url
The url of the page this event occurred at. 
curl https://api.hellotext.com/v1/attribution/events \
  -d action="coupon.redeemed" \
  -d coupon=wx4Vn4no \
  -d session=2KAGgAgm \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "status": "received"
}

Track form events

Track the events performed by your customers when they complete a form. Available actions are form.completed.

The monetary values associated to the form completions will be aggregated to the campaign reportings.

Parameters
action
enum
Required
The name of the action to track.
Possible enum values
form.completed
amount
float
Monetary amount that represents the revenue associated to this tracked event. Default value is null.
currency
currency
Currency for the amount given in ISO 4217 format. Default value is always USD.
form
string
Required
Unique identifier of the form object associated to this event.
form_parameters
hash
A hash the can be passed instead of form parameter. The form will be created and have the event tracked for. Show child attributes
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
Required if session is not specified. Unique identifier of the profile object this event belongs to. If not explicitly specified, the profile identifier can be inherited when the session parameter is specified and the session is already associated to a profile or becomes later attached to one.
session
string
Required if profile is not specified. Identifier of the session object this event belongs to. Sessions are identifiers generated automatically from clicks by visitors on short links or from the Hellotext.js library when keeping track of anonymous visitors. It is a way to track events on the client-side without authenticating or disclosing the profile identifier allowing to associate it later to a profile securely on the server-side. More on Sessions.
tracked_at
epoch
Original date when the event happened. This is useful if you want to record an event that happened in the past. If no value is provided its value will be the same from created_at.
url
url
The url of the page this event occurred at. 
curl https://api.hellotext.com/v1/attribution/events \
  -d action="form.completed" \
  -d form=wx4Vn4no \
  -d session=2KAGgAgm \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "status": "received"
}

Track order events

Track the events related to the lifecycle of your customer's orders. Available actions are order.placed when an order is placed by a customer, order.confirmed when is confirmed, order.cancelled if cancelled and order.shipped when shipped.

The monetary values associated to the orders will be aggregated to the campaign reportings.

Parameters
action
enum
Required
The name of the action to track.
Possible enum values
order.cancelled
order.confirmed
order.delivered
order.placed
order.printed_label
order.shipped
amount
float
Monetary amount that represents the revenue associated to this tracked event. Default value is null.
currency
currency
Currency for the amount given in ISO 4217 format. Default value is always USD.
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
Required
Unique identifier of the order object associated to this event.
order_parameters
hash
A hash the can be passed instead of order parameter. The order will be created and have the event tracked for. Show child attributes
profile
string
Required if session is not specified. Unique identifier of the profile object this event belongs to. If not explicitly specified, the profile identifier can be inherited when the session parameter is specified and the session is already associated to a profile or becomes later attached to one.
session
string
Required if profile is not specified. Identifier of the session object this event belongs to. Sessions are identifiers generated automatically from clicks by visitors on short links or from the Hellotext.js library when keeping track of anonymous visitors. It is a way to track events on the client-side without authenticating or disclosing the profile identifier allowing to associate it later to a profile securely on the server-side. More on Sessions.
tracked_at
epoch
Original date when the event happened. This is useful if you want to record an event that happened in the past. If no value is provided its value will be the same from created_at.
url
url
The url of the page this event occurred at. 
curl https://api.hellotext.com/v1/attribution/events \
  -d action="order.placed" \
  -d order=wx4Vn4no \
  -d session=2KAGgAgm \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "status": "received"
}

Track product events

Track the events of purchases made by your customers. If your customers places orders, you can track the order actions instead. Available product actions are product.purchased when a customer purchases a product and product.viewed when a product is viewed from a product page.

The monetary values associated to the product purchase will be aggregated to the campaign reportings.

This endpoint can be used with Products and Product variants. If you want to track an existing Product or Product Variant, make sure to either pass an existing record's id, reference or sku. If you want to create a new Product, you should pass the product_parameters parameter. Similarly, if you want to create a new Product Variant, make sure to pass the product_variant_parameters instead.

Parameters
action
enum
Required
The name of the action to track.
Possible enum values
product.purchased
product.viewed
amount
float
Monetary amount that represents the revenue associated to this tracked event. Default value is null.
currency
currency
Currency for the amount given in ISO 4217 format. Default value is always USD.
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.
product
string
Required
The id, reference or sku of an existing product object. Optional when you pass product_parameters or product_variant. Required when passing product_variant_parameters.
product_parameters
hash
A hash the can be passed instead of product parameter. The product will be created and have the event tracked for. Show child attributes
product_variant
string
Required
The id, reference or sku of an existing product variant object. Optional when you specify product_variant_parameters.
product_variant_parameters
hash
A hash that can be passed instead of product_variant parameter. The product variant will be created and have the event tracked for. When passing this parameter, make sure to also specify the product via the product parameter. Show child attributes
profile
string
Required if session is not specified. Unique identifier of the profile object this event belongs to. If not explicitly specified, the profile identifier can be inherited when the session parameter is specified and the session is already associated to a profile or becomes later attached to one.
session
string
Required if profile is not specified. Identifier of the session object this event belongs to. Sessions are identifiers generated automatically from clicks by visitors on short links or from the Hellotext.js library when keeping track of anonymous visitors. It is a way to track events on the client-side without authenticating or disclosing the profile identifier allowing to associate it later to a profile securely on the server-side. More on Sessions.
tracked_at
epoch
Original date when the event happened. This is useful if you want to record an event that happened in the past. If no value is provided its value will be the same from created_at.
url
url
The url of the page this event occurred at. 
curl https://api.hellotext.com/v1/attribution/events \
  -d action="product.purchased" \
  -d product=vxqQJ3Yg \
  -d session=2KAGgAgm \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "status": "received"
}

Track refund events

Track the events related to the refunds requested by your customers. Available actions are refund.requested and refund.received.

The monetary values associated to the refunds issued will be aggregated to the campaign reportings.

Parameters
action
enum
Required
The name of the action to track.
Possible enum values
refund.received
refund.requested
amount
float
Monetary amount that represents the revenue associated to this tracked event. Default value is null.
currency
currency
Currency for the amount given in ISO 4217 format. Default value is always USD.
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
Required if session is not specified. Unique identifier of the profile object this event belongs to. If not explicitly specified, the profile identifier can be inherited when the session parameter is specified and the session is already associated to a profile or becomes later attached to one.
refund
string
Required
Unique identifier of the refund object associated to this event.
refund_parameters
hash
A hash the can be passed instead of refund parameter. The refund will be created and have the event tracked for. Show child attributes
session
string
Required if profile is not specified. Identifier of the session object this event belongs to. Sessions are identifiers generated automatically from clicks by visitors on short links or from the Hellotext.js library when keeping track of anonymous visitors. It is a way to track events on the client-side without authenticating or disclosing the profile identifier allowing to associate it later to a profile securely on the server-side. More on Sessions.
tracked_at
epoch
Original date when the event happened. This is useful if you want to record an event that happened in the past. If no value is provided its value will be the same from created_at.
url
url
The url of the page this event occurred at. 
curl https://api.hellotext.com/v1/attribution/events \
  -d action="refund.added" \
  -d refund=wx4Vn4no \
  -d product=vxqQJ3Yg \
  -d session=2KAGgAgm \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "status": "received"
}

Track custom events

Hellotext provides a list of ready-to-use actions to track the most common customers interactions with your business such as purchases, visits to your site, products added to cart, form completions and more. However these are not always enough and sometimes you need a little more flexibility when needing to define specific actions for your business needs.

It is possible to specify any customized action name when tracking events as long as the action object has been previously created. Once the action is created you can simply use its name to track a new event.

Please keep in mind that monetary values passed to these event will be aggregated to the campaign reportings as sales.

See Actions.

Parameters
action
string
Required
The name of the custom action to track. The custom action must be previously created.
amount
float
Monetary amount that represents the revenue associated to this tracked event. Default value is null.
app
string
Unique identifier of the app object associated to this event.
coupon
string
Unique identifier of the app object associated to this event.
currency
currency
Currency for the amount given in ISO 4217 format. Default value is always USD.
form
string
Unique identifier of the form object associated to this event.
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
Unique identifier of the order object associated to this event.
product
string
Unique identifier of the product object associated to this event.
profile
string
Required if session is not specified. Unique identifier of the profile object this event belongs to. If not explicitly specified, the profile identifier can be inherited when the session parameter is specified and the session is already associated to a profile or becomes later attached to one.
refund
string
Unique identifier of the refund object associated to this event.
session
string
Required if profile is not specified. Identifier of the session object this event belongs to. Sessions are identifiers generated automatically from clicks by visitors on short links or from the Hellotext.js library when keeping track of anonymous visitors. It is a way to track events on the client-side without authenticating or disclosing the profile identifier allowing to associate it later to a profile securely on the server-side. More on Sessions.
tracked_at
epoch
Original date when the event happened. This is useful if you want to record an event that happened in the past. If no value is provided its value will be the same from created_at.
url
url
The url of the page this event occurred at. 
curl https://api.hellotext.com/v1/attribution/events \
  -d action="signup_form.completed" \
  -d session=2KAGgAgm \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "status": "received"
}

Actions

Hellotext provides a basic set of actions, perfect for starting your next attribution campaign. But, when the need arises to track different actions not provided by Hellotext you can extend the set of available actions by creating your own custom actions.

You are free to name the actions any way you like. We recommend to take a dot approach when naming your actions, to have them scoped and states, for example custom actions can be like the following.

See Track custom events for more information.

Custom action examples
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

The action object

Attributes
id
String
Unique identifier of the object.
type
Type
Type of object. This is always action.
created_at
Epoch
Date of creation of the object.
goal
Boolean
Is this action used as a metric for KPIs?. Defaults to false. Setting it to true will allow events with this action to be used as a metric for KPIs displayed in the Campaigns and Journeys.
name
String
The name of the action. This is the name used in the action parameter when tracking an event. Duplicate names are not allowed.
passive
Boolean
Is this action passive or not?. Defaults to true.

Passive events are events that don't affect the order of conversations in the inbox, when a passive event is recorded, the conversation's position is not changed. Passive events are not displayed on the Inbox, they are only displayed in the Activity Trail of a Profile.

Non-passive events are events that affect the order of conversations in the inbox, when an active event is recorded, the conversation's position is updated and is moved to the top so it can be handled. Non-passive events are recorded in the Inbox and the Activity Trail.

Generally, if the action is important(requires an action by your team) and you want to easily see it in the Inbox when it happens, set this attribute as false. However, if the action is not important, you can mark it as passive.
title
String
Human-friendly alternative name used on Segments and Journeys. If not provided, it will be the same as the name parameter. 
{
  "id": "Wvqz2qD1",
  "type": "action",
  "created_at": 1665684173,
  "goal": false,
  "name": "signup_form.completed",
  "passive": true,
  "title": "Signup-form completed"
}

Create an action

Creates a new action.

Parameters
goal
Boolean
Is this action used as a metric for KPIs?. Defaults to false. Setting it to true will allow events with this action to be used as a metric for KPIs displayed in the Campaigns and Journeys.
name
String
Required
The name of the action. This is the name used in the action parameter when tracking an event. Duplicate names are not allowed.
passive
Boolean
Is this action passive or not? Defaults to true.
title
String
Human-friendly alternative name used on Segments and Journeys. If not provided, it will be the same as the name parameter. 
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"
}

Retrieve an action

Retrieves an existing action.

 
curl -G https://api.hellotext.com/v1/attribution/actions/Wvqz2qD1 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

Update an action

Updates the specified action with the provided information.

Parameters
goal
Boolean
Is this action used as a metric for KPIs?. Defaults to false. Setting it to true will allow events with this action to be used as a metric for KPIs displayed in the Campaigns and Journeys.
name
String
Required
The name of the action. This is the name used in the action parameter when tracking an event. Duplicate names are not allowed.
passive
Boolean
Is this action passive or not? Defaults to true.
title
String
Human-friendly alternative name used on Segments and Journeys. If not provided, it will be the same as the name parameter. 
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"
}

Delete an action

Permanently deletes the specified action.

This action is irreversible. Deleting an action will also delete all of the tracked events associated with it. Be careful when using this endpoint.

 
curl -X DELETE https://api.hellotext.com/v1/attribution/actions/Wvqz2qD1 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "id": "Wvqz2qD1",
  "type": "action",
  "deleted": true
}

List all actions

Lists existing actions sorting by most recent ones. Pagination parameters are available in lists.

Parameters
ending_before
String
Display results listed before (more recent) than the given id.
limit
integer
Limit how many results to show. Default is 25. Maximum is 100.
starting_after
String
Display results listed after (older) than the given id. 
curl -G https://api.hellotext.com/v1/attribution/actions 
 -d limit=5 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "actions": [
    {
      "id": "Wvqz2qD1",
      "type": "action",
      "created_at": 1665684173,
      "goal": false,
      "name": "signup_form.completed",
      "passive": true,
      "title": "Signup-form completed"
    },
    "{...}",
    "{...}"
  ]
}

Apps

App objects represent the applications your own or manage that your audience interact with. For example these could be your iOS or Android apps.

You can track the events from your audience interacting with your apps. For example when someone installs an app, removes it or spends any amount.

Learn how Track app events.

 
  POST /v1/attribution/apps
   GET /v1/attribution/apps/:id
 PATCH /v1/attribution/apps/:id
DELETE /v1/attribution/apps/:id
   GET /v1/attribution/apps

The app object

Attributes
id
string
Unique identifier of the tracking event.
type
string
Type of object. This is always app.
created_at
epoch
Date of creation of the app object.
image_url
url
An URL of the application icon in high resolution. We will download the image and store it on our servers.
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
The name of the application. Duplicate names are not allowed. 
{
  "id": "xnqJQ47v",
  "type": "app",
  "created_at": 1665684173
  "image_url": "https://www.beautyandcare.com/apps/awesome.jpg",
  "metadata": {},
  "name": "Beauty & Care",
}

Create an app

Creates a new app.

Parameters
image_url
url
An URL of the application icon in high resolution. We will download the image and store it on our servers.
name
string
Required
The name of the application. Duplicate names are not allowed. 
curl https://api.hellotext.com/v1/attribution/apps \
  -d name="Beauty & Care" \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "id": "xnqJQ47v",
  "type": "app",
  "created_at": 1665684173
  "image_url": null,
  "metadata": {},
  "name": "Beauty & Care",
}

Retrieve an app

Retrieves an existing app.

 
curl -G https://api.hellotext.com/v1/attribution/apps/xnqJQ47v \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

Update an app

Updates the specified app with the provided information.

Parameters
image_url
url
An URL of the application icon in high resolution. We will download the image and store it on our servers. Providing null will remove the attached image
name
string
The name of the application. Duplicate names are not allowed. 
curl https://api.hellotext.com/v1/attribution/apps/xnqJQ47v \
  -d name="Beauty & More" \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "id": "xnqJQ47v",
  "type": "app",
  "created_at": 1665684173
  "image_url": null,
  "metadata": {},
  "name": "Beauty & More",
}

Delete an app

Permanently deletes the specified app.

 
curl -X DELETE https://api.hellotext.com/v1/attribution/apps/xnqJQ47v \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "id": "xnqJQ47v",
  "type": "app",
  "deleted": true
}

List all apps

Lists existing apps sorting by most recent ones. Pagination parameters are available in lists.

Parameters
starting_after
string
Display results listed after (older) than the given id.
ending_before
string
Display results listed before (more recent) than the given id.
limit
integer
Limit how many results to show. Default is 25. Maximum is 100. 
curl -G https://api.hellotext.com/v1/attribution/apps \
  -d limit=5 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "apps": [
    {
      "id": "xnqJQ47v",
      "type": "app",
      "created_at": 1665684173
      "image_url": "https://www.beautyandcare.com/apps/awesome.jpg",
      "metadata": {},
      "name": "Beauty & Care",
    },
    {...},
    {...}
  ]
}

Carts

Carts objects represent shopping carts objects that can be used to determine what items the profile has in the cart at a moment in time.

Carts objects act as logical groups where you can group multiple products added into a cart together.

You can track when items are added to the cart, removed from the cart, or when the cart was abandoned.

Learn how Track cart events.

  • POST

    v1/attribution/carts

  • GET

    v1/attribution/carts/:id

  • PATCH

    v1/attribution/carts/:id

  • DELETE

    v1/attribution/carts/:id

  • GET

    v1/attribution/carts

The cart object

Attributes
id
String
Unique identifier of the object.
type
Type
Type of object. This is always cart.
created_at
Epoch
Date of creation of the object.
items
array
A collection of items included in the cart at the current moment in time. Show child attributes
metadata
Hash
Set of key-value pairs that you can attach to the cart. This can be useful for storing additional information about the object in a structured format.
profile
profile
The identifier of the profile that this cart belongs to.
reference
String
The cart number or original identifier from the external source that created the cart.
session
String
The identifier of the session that this cart belongs to.
source
String
The source or platform where this cart was generated from. 
{
  "id": "wx4Vn4no",
  "type": "cart",
  "created_at": 1665684173,
  "items": [
    {
      "id": "wx4Vn4no",
      "type": "cart_item",
      "created_at": 1665684173,
      "price": {
        "amount": "100.00",
        "converted_amount": "100.00",
        "converted_currency": "EUR",
        "currency": "USD"
      },
      "product": "vxqQJ3Yg",
      "quantity": 1
    },
    "{...}",
    "{...}"
  ],
  "metadata": {
  },
  "profile": "MzYwlE50",
  "reference": "ABC123",
  "session": "Vdqlg4nL",
  "source": null
}

Create a cart

Creates a new cart.

Parameters
items
array
A collection of cart items that are included in this cart. Show child attributes
profile
profile
The unique identifier of the profile that this cart belongs to. Required if no session is provided.
reference
String
The cart number or original identifier from the external source that created the cart.
session
String
The unique identifier of the session that this cart belongs to. Required if no profile is provided. It can be used to associate the cart with an undefined profile. And later attaching the Cart to the profile once the profile is known
source
String
The source or platform where this cart was generated from. 
curl -X POST https://api.hellotext.com/v1/attribution/carts 
 -d metadata[attribute1]=value1 
 -d metadata[attribute2]=value2 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "id": "wx4Vn4no",
  "type": "cart",
  "created_at": 1665684173,
  "items": [
    {
      "id": "wx4Vn4no",
      "type": "cart_item",
      "created_at": 1665684173,
      "price": {
        "amount": "100.00",
        "converted_amount": "100.00",
        "converted_currency": "EUR",
        "currency": "USD"
      },
      "product": "vxqQJ3Yg",
      "quantity": 1
    },
    "{...}",
    "{...}"
  ],
  "metadata": {
    "attribute1": "value1",
    "attribute2": "value2"
  },
  "profile": "MzYwlE50",
  "reference": "ABC123",
  "session": "Vdqlg4nL",
  "source": null
}

Retrieve a cart

Retrieves an existing cart.

 
curl -G https://api.hellotext.com/v1/attribution/carts/wx4Vn4no 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

Update a cart

Updates the specified cart with the provided information.

Parameters
items
array
A collection of cart items that replace the current items in the cart. Passing an empty value of [] will remove all the items from the cart. Ignoring the parameter will not change the current items in the cart. Show child attributes
new_items
array
A collection of new cart items to add to the cart. Consider using the Tracking Carts API to add items to an existing cart, as it will also be displayed on the Activity Trail of a Profile. Show child attributes
profile
profile
The unique identifier of the profile that this cart belongs to. Required if no session is provided.
reference
String
The cart number or original identifier from the external source that created the cart.
session
String
The unique identifier of the session that this cart belongs to. Required if no profile is provided. It can be used to associate the cart with an undefined profile. And later attaching the Cart to the profile once the profile is known
source
String
The source or platform where this cart was generated from. 
curl -X PATCH https://api.hellotext.com/v1/attribution/carts/wx4Vn4no 
 -d metadata[attribute1]=value1 
 -d metadata[attribute2]=value2 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "id": "wx4Vn4no",
  "type": "cart",
  "created_at": 1665684173,
  "items": [
    {
      "id": "wx4Vn4no",
      "type": "cart_item",
      "created_at": 1665684173,
      "price": {
        "amount": "100.00",
        "converted_amount": "100.00",
        "converted_currency": "EUR",
        "currency": "USD"
      },
      "product": "vxqQJ3Yg",
      "quantity": 1
    },
    "{...}",
    "{...}"
  ],
  "metadata": {
    "attribute1": "value1",
    "attribute2": "value2"
  },
  "profile": "MzYwlE50",
  "reference": "ABC123",
  "session": "Vdqlg4nL",
  "source": null
}

Delete a cart

Permanently deletes the specified cart.

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

List all carts

Lists existing carts sorting by most recent ones. Pagination parameters are available in lists.

Parameters
ending_before
String
Display results listed before (more recent) than the given id.
limit
integer
Limit how many results to show. Default is 25. Maximum is 100.
starting_after
String
Display results listed after (older) than the given id. 
curl -G https://api.hellotext.com/v1/attribution/carts 
 -d limit=5 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "carts": [
    {
      "id": "wx4Vn4no",
      "type": "cart",
      "created_at": 1665684173,
      "items": [
        {
          "id": "wx4Vn4no",
          "type": "cart_item",
          "created_at": 1665684173,
          "price": {
            "amount": "100.00",
            "converted_amount": "100.00",
            "converted_currency": "EUR",
            "currency": "USD"
          },
          "product": "vxqQJ3Yg",
          "quantity": 1
        },
        "{...}",
        "{...}"
      ],
      "metadata": {
      },
      "profile": "MzYwlE50",
      "reference": "ABC123",
      "session": "Vdqlg4nL",
      "source": null
    },
    "{...}",
    "{...}"
  ]
}

Events

Events represent the individual actions of your customers that you want to track. All events are always associated to a profile through a session or profile.

An event always requires a action that you want to track. See the Tracking section for more information on the different ways to track events.

 
  POST /v1/attribution/events
   GET /v1/attribution/events/:id
 PATCH /v1/attribution/events/:id
DELETE /v1/attribution/events/:id
   GET /v1/attribution/events

The event object

Attributes
id
string
Unique identifier of the event object.
type
string
Type of object. This is always event.
action
hash
A hash that represents the action object. Show child attributes
amount
float
Monetary amount that represents the revenue associated to this tracked event. Default value is null.
converted_amount
string
Monetary amount that represents the amount converted to the business' reporting currency.
converted_amount_currency
string
Currency for the converted_amount given in ISO 4217 format
created_at
epoch
Date of creation of the event object.
currency
currency
Currency for the amount given in ISO 4217 format. Default value is always USD.
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
Required if session is not specified. Unique identifier of the profile object this event belongs to. If not explicitly specified, the profile identifier can be inherited when the session parameter is specified and the session is already associated to a profile or becomes later attached to one.
session
string
Required if profile is not specified. Identifier of the session object this event belongs to. Sessions are identifiers generated automatically from clicks by visitors on short links or from the Hellotext.js library when keeping track of anonymous visitors. It is a way to track events on the client-side without authenticating or disclosing the profile identifier allowing to associate it later to a profile securely on the server-side. More on Sessions.
trackable
hash
A hash that represents the object tracked. Show child attributes
tracked_at
epoch
Original date when the event happened. This is useful if you want to record an event that happened in the past. If no value is provided its value will be the same from created_at.
url
url
The url of the page this event occurred at. 
{
  "id": "xnqJQ47v",
  "type": "event",
  "action": {
    "id": "Wvqz2qD1",
    "name": "order.confirmed",
    "title": "Product purchased"
  },
  "amount": 199.95,
  "converted_amount": "19.90",
  "converted_amount_currency": "EUR",
  "created_at": 1665684173,
  "currency": "USD",
  "metadata": {},
  "profile": "MzYwlE50",
  "session": "Vdqlg4nL",
  "trackable": {
    "id": "ro4a731w",
    "type": "order",
    "amount": 199.95,
    "currency": "USD",
    "product_ids": ["xnqJQ47v"]
  },
  "tracked_at": "1665684173",
}

Retrieve an event

Retrieves an existing event.

 
curl -G https://api.hellotext.com/v1/attribution/events/xnqJQ47v \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

Update an event

Updates the specified event with the provided information.

Parameters
action
string
The name of the action
amount
float
Monetary amount that represents the revenue associated to this tracked event. Default value is null.
app
string
Unique identifier of the app object associated to this event.
currency
currency
Currency for the amount given in ISO 4217 format. Default value is always USD.
form
string
Unique identifier of the form object associated to this event.
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
Unique identifier of the order object associated to this event.
product
string
Unique identifier of the product object associated to this event.
product_ids
string
An array of product identifiers associated to this event.
profile
string
Required if session is not specified. Unique identifier of the profile object this event belongs to. If not explicitly specified, the profile identifier can be inherited when the session parameter is specified and the session is already associated to a profile or becomes later attached to one.
refund
string
Unique identifier of the refund object associated to this event.
session
string
Required if profile is not specified. Identifier of the session object this event belongs to. Sessions are identifiers generated automatically from clicks by visitors on short links or from the Hellotext.js library when keeping track of anonymous visitors. It is a way to track events on the client-side without authenticating or disclosing the profile identifier allowing to associate it later to a profile securely on the server-side. More on Sessions.
tracked_at
epoch
Original date when the event happened. This is useful if you want to record an event that happened in the past. If no value is provided its value will be the same from created_at.
url
url
The url of the page this event occurred at. 
curl https://api.hellotext.com/v1/attribution/events/xnqJQ47v \
  -d amount=295.00 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "id": "xnqJQ47v",
  "type": "event",
  "action": {
    "id": "Wvqz2qD1",
    "name": "order.confirmed",
    "title": "Product purchased"
  },
  "amount": 295.00,
  "converted_amount": "19.90",
  "converted_amount_currency": "EUR",
  "created_at": 1665684173,
  "currency": "USD",
  "metadata": {},
  "profile_id": "MzYwlE50",
  "session_id": "Vdqlg4nL",
  "trackable": {
    "id": "ro4a731w",
    "type": "order",
    "amount": 199.95,
    "currency": "USD",
    "product_ids": ["xnqJQ47v"]
  },
  "tracked_at": "1665684173",
}

Delete an event

Permanently deletes the specified event.

 
curl -X DELETE https://api.hellotext.com/v1/attribution/events/xnqJQ47v \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "id": "xnqJQ47v",
  "type": "event",
  "deleted": true
}

List all events

Lists existing events sorting by most recent ones. Pagination parameters are available in lists.

Parameters
starting_after
string
Display results listed after (older) than the given id.
ending_before
string
Display results listed before (more recent) than the given id.
limit
integer
Limit how many results to show. Default is 25. Maximum is 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"
    },
    {...},
    {...}
  ]
}

Forms

Forms objects represent form objects that you can use when tracking actions such as form.completed.

Forms objects act as logical groups where you can group multiple actions to the same object for better reporting.

 
  POST /v1/attribution/forms
   GET /v1/attribution/forms/:id
 PATCH /v1/attribution/forms/:id
DELETE /v1/attribution/forms/:id
   GET /v1/attribution/forms

The form object

Attributes
id
string
Unique identifier of the form object.
type
string
Type of object. This is always form.
created_at
epoch
Date of creation of the form object.
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
Any name given to the form for reference. Duplicate names are not allowed. 
{
  "id": "O8lOzkwa",
  "type": "form",
  "created_at": 1665684173
  "metadata": {},
  "name": "Sign-Up Form",
}

Create a form

Creates a new form.

Parameters
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
Required
Any name given to the form for reference. Duplicate names are not allowed. 
curl https://api.hellotext.com/v1/attribution/forms \
  -d name="Sign-Up Form" \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "id": "O8lOzkwa",
  "type": "form",
  "created_at": 1665684173
  "metadata": {}
  "name": "Sign-Up Form",
}

Retrieve a form

Retrieves an existing form.

 
curl -G https://api.hellotext.com/v1/attribution/forms/O8lOzkwa \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

Update a form

Updates the specified form with the provided information.

Parameters
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
Any name given to the form for reference. Duplicate names are not allowed. 
curl https://api.hellotext.com/v1/attribution/forms/O8lOzkwa \
  -d name="Completion Form" \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "id": "O8lOzkwa",
  "type": "form",
  "created_at": 1665684173
  "metadata": {},
  "name": "Completion Form",
}

Delete a form

Permanently deletes the specified form.

 
curl -X DELETE https://api.hellotext.com/v1/attribution/forms/O8lOzkwa \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "id": "O8lOzkwa",
  "type": "form",
  "deleted": true
}

List all forms

Lists existing forms sorting by most recent ones. Pagination parameters are available in lists.

Parameters
starting_after
string
Display results listed after (older) than the given id.
ending_before
string
Display results listed before (more recent) than the given id.
limit
integer
Limit how many results to show. Default is 25. Maximum is 100. 
curl -G https://api.hellotext.com/v1/attribution/forms \
  -d limit=5 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "forms": [
    {
      "id": "O8lOzkwa",
      "type": "form",
      "created_at": 1665684173
      "metadata": {},
      "name": "Sign-Up Form",
    },
    {...},
    {...}
  ]
}

The Order object

Orders represent groups of products that you can use when tracking order.placed, order.confirmed, order.shipped, order.cancelled and order.delivered events.

  • POST

    v1/attribution/orders

  • GET

    v1/attribution/orders/:id

  • PATCH

    v1/attribution/orders/:id

  • DELETE

    v1/attribution/orders/:id

  • GET

    v1/attribution/orders

The Order object

Attributes
id
String
Unique identifier of the order object.
type
Type
Type of object. This is always order.
created_at
Epoch
Date of creation of the order object.
delivery
Enum
Specifies how the order must be delivered to the customer. It can be use on Journeys to set different conditions based on this value. Possible values are collect when customers buys directly on store or pickup from store and deliver when shipping the package to the customer address. This attribute is not set by default.
Possible enum values
collect
deliver
items
array
A collection of items included in the order. Show child attributes
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.
reference
String
The order number or original identifier from the external source that created the order.
source
String
The identifier of the platform where the order was created from.
total
hash
A hash representing the total and converted total of the order. Show child attributes 
{
  "id": "ro4a731w",
  "type": "order",
  "created_at": 1665684173,
  "delivery": "deliver",
  "items": [
    {
      "id": "vxqQJ3Yg",
      "type": "order_item",
      "price": {
        "amount": "395.00",
        "currency": "USD",
        "converted_amount": "19.90",
        "converted_currency": "EUR"
      },
      "product": "vxqQJ3Yg",
      "quantity": 1
    }
  ],
  "metadata": {
  },
  "reference": "1234",
  "source": null,
  "total": {
    "amount": "395.00",
    "converted_amount": "19.90",
    "converted_amount_currency": "EUR",
    "currency": "USD"
  }
}

Create an Order

Creates a new order.

Attributes
delivery
Enum
Specifies how the order must be delivered to the customer. It can be use on Journeys to set different conditions based on this value. Possible values are collect when customers buys directly on store or pickup from store and deliver when shipping the package to the customer address. This attribute is not set by default.
Possible enum values
collect
deliver
items
array
A collection of items included in the order. Show child attributes
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.
reference
String
The order number or original identifier from the external source that created the order.
source
String
The identifier of the platform where the order was created from. 
curl -X POST https://api.hellotext.com/v1/attribution/orders 
 -d product="vxqQJ3YQ" 
 -d name="Yeezy boost 350 v2" 
 -d sku="1234567890" 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "id": "ro4a731w",
  "type": "order",
  "created_at": 1665684173,
  "delivery": "deliver",
  "items": [
    {
      "id": "vxqQJ3Yg",
      "type": "order_item",
      "price": {
        "amount": "395.00",
        "currency": "USD",
        "converted_amount": "19.90",
        "converted_currency": "EUR"
      },
      "product": "vxqQJ3Yg",
      "quantity": 1
    }
  ],
  "metadata": {
  },
  "reference": "1234",
  "source": null,
  "total": {
    "amount": "395.00",
    "converted_amount": "19.90",
    "converted_amount_currency": "EUR",
    "currency": "USD"
  },
  "product": "vxqQJ3YQ",
  "name": "Yeezy boost 350 v2",
  "sku": "1234567890"
}

Retrieve an Order

Retrieves the details of an existing order.

 
curl -G https://api.hellotext.com/v1/attribution/orders/vxqQJ3Yg 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "id": "ro4a731w",
  "type": "order",
  "created_at": 1665684173,
  "delivery": "deliver",
  "items": [
    {
      "id": "vxqQJ3Yg",
      "type": "order_item",
      "price": {
        "amount": "395.00",
        "currency": "USD",
        "converted_amount": "19.90",
        "converted_currency": "EUR"
      },
      "product": "vxqQJ3Yg",
      "quantity": 1
    }
  ],
  "metadata": {
  },
  "reference": "1234",
  "source": null,
  "total": {
    "amount": "395.00",
    "converted_amount": "19.90",
    "converted_amount_currency": "EUR",
    "currency": "USD"
  }
}

Update an Order

Updates an existing order.

Attributes
delivery
Enum
Specifies how the order must be delivered to the customer. It can be use on Journeys to set different conditions based on this value. Possible values are collect when customers buys directly on store or pickup from store and deliver when shipping the package to the customer address. This attribute is not set by default.
Possible enum values
collect
deliver
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.
reference
String
The order number or original identifier from the external source that created the order.
source
String
The identifier of the platform where the order was created from. 
curl -X PATCH https://api.hellotext.com/v1/attribution/orders/vxqQJ3Yg 
 -d name="Yeezy boost 350 v2" 
 -d sku="5678" 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "id": "vxqQJ3YQ",
  "type": "order",
  "created_at": 1665684173,
  "delivery": "deliver",
  "items": [
    {
      "id": "vxqQJ3Yg",
      "type": "order_item",
      "price": {
        "amount": "395.00",
        "currency": "USD",
        "converted_amount": "19.90",
        "converted_currency": "EUR"
      },
      "product": "vxqQJ3Yg",
      "quantity": 1
    }
  ],
  "metadata": {
  },
  "reference": "1234",
  "source": null,
  "total": {
    "amount": "395.00",
    "converted_amount": "19.90",
    "converted_amount_currency": "EUR",
    "currency": "USD"
  },
  "name": "Yeezy boost 350 v2",
  "sku": "5678"
}

Destroy an Order

Deletes an order.

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

List all Orders

Lists existing orders sorting by most recent ones. Pagination parameters are available in lists.

Parameters
ending_before
String
Display results listed before (more recent) than the given id.
limit
integer
Limit how many results to show. Default is 25. Maximum is 100.
starting_after
String
Display results listed after (older) than the given id. 
curl -G https://api.hellotext.com/v1/attribution/orders 
 -d limit=5 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "orders": [
    {
      "id": "ro4a731w",
      "type": "order",
      "created_at": 1665684173,
      "delivery": "deliver",
      "items": [
        {
          "id": "vxqQJ3Yg",
          "type": "order_item",
          "price": {
            "amount": "395.00",
            "currency": "USD",
            "converted_amount": "19.90",
            "converted_currency": "EUR"
          },
          "product": "vxqQJ3Yg",
          "quantity": 1
        }
      ],
      "metadata": {
      },
      "reference": "1234",
      "source": null,
      "total": {
        "amount": "395.00",
        "converted_amount": "19.90",
        "converted_amount_currency": "EUR",
        "currency": "USD"
      }
    },
    "{...}",
    "{...}"
  ]
}

The Order Item object.

Describes a product in an order.

  • POST

    v1/attribution/orders/:order/items

  • PATCH

    v1/attribution/orders/:order/items/:id

  • DELETE

    v1/attribution/orders/:order/items/:id

The Order Item object.

Attributes
id
String
The unique identifier for the order item.
type
Type
The type of the object. This is always order_item.
created_at
Epoch
Date of creation of the object.
price
hash
A hash representing the price and converted price of the order item. Show child attributes
product
product
The unique identifier of the product.
quantity
float
The quantity of the product. 
{
  "id": "vxqQJ3Yg",
  "type": "order_item",
  "price": {
    "amount": "395.00",
    "currency": "USD",
    "converted_amount": "19.90",
    "converted_currency": "EUR"
  },
  "product": "vxqQJ3Yg",
  "quantity": 1
}

Create an Order Item

Adds a product to an order.

The Order's total will be updated automatically to reflect the new item.

Attributes
price
hash
A hash representing the price and converted price of the order item. When unspecified, the property will be inherited from the product. Show child attributes
product
product
Required
A unique identifier (id, reference or sku) of a product or product variant.
quantity
float
The quantity of the product. Defaults to 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"
}

Update an Order Item

Update a specific item's attributes.

The order's total will be updated automatically to reflect the changes.

Attributes
price
hash
A hash representing the price and converted price of the order item. When unspecified, the property will be inherited from the product. Show child attributes
quantity
float
The quantity of the product. Defaults to 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"
}

Delete an Order Item

Removes a product from an order.

The Order's total will be updated automatically to reflect the removed item. 

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
}

Products

Product objects represent products that you can use to track actions through its lifecycle such as product.purchased and product.viewed or cart.added and cart.removed.

Product objects act as logical groups where you can group multiple actions to the same object for better reporting.

  • 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

Attributes
id
String
Unique identifier of the object.
type
Type
Type of object. This is always product.
brand
String
Name of the brand of the product.
categories
array
A collection of categories represented as an array of strings.
collection
array
Collection name for products that belongs to a collection.
created_at
Epoch
Date of creation of the object.
image_url
URL
An URL of the application icon in high resolution. Corresponds to the first variant.
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
Any name given to the product for reference. This is also the name of the default first variant.
price
hash
A hash representing the price of the product and the associated identifier. It also contains the converted_amount and converted_currency. Show child attributes
reference
String
The product's default variant number or original identifier from the external source that created the product.
sku
String
A case-sensitive identifier for the product's default variant. For effective tracking and sales reporting, SKUs should be unique and no two product variants should include the same SKU in their details.
source
String
The source or platform where this product was generated from. Corresponds to the first variant.
tags
array
A collection of tags represented as an array of strings.
variants
array
An array of all variants of the current product. Each array contains the unique aspects of the variant compared to the parent. Each variant contains an id attribute that you can use to delete or update that specific variant. Show child attributes 
{
  "id": "vxqQJ3Yg",
  "type": "product",
  "brand": "Adidas",
  "categories": [
    "shoes"
  ],
  "collection": [
    "350 v2"
  ],
  "created_at": 1665684173,
  "metadata": {
  },
  "name": "Yeezy Boost 350 v2",
  "price": {
    "amount": 220.0,
    "converted_amount": 220.0,
    "converted_currency": "EUR",
    "currency": "USD"
  },
  "reference": null,
  "sku": "1234567890",
  "source": null,
  "tags": [
    "Sneakers"
  ],
  "variants": [
    {
      "id": "vxqQJ3Yg",
      "type": "product_variant",
      "created_at": 1665684173,
      "image_url": "https://www.primesneakers.com/products/yeezy-350-v2.jpg",
      "metadata": {
      },
      "name": "Yeezy Boost 350 v2",
      "price": {
        "amount": 220.0,
        "converted_amount": 220.0,
        "converted_currency": "EUR",
        "currency": "USD"
      },
      "product": "vxqQJ3YQ",
      "reference": null,
      "sku": "1234567890",
      "source": null
    },
    "{...}",
    "{...}"
  ]
}

Create a product

Creates a new product.

Parameters
brand
String
Name of the brand of the product.
categories
array
A collection of categories represented as an array of strings.
collection
array
Collection name for products that belongs to a collection.
image_url
URL
An URL pointing to an image of the product. We will download the image and store it on our servers. Please make sure the URL is publicly accessible because we will not be able to access it if it requires authentication.
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
Required
Any name given to the product for reference. This is also the name of the default first variant.
price
hash
A hash representing the price of the product and the associated identifier. It also contains the converted_amount and converted_currency. Show child attributes
reference
String
The product's default variant number or original identifier from the external source that created the product.
sku
String
A case-sensitive identifier for the product's default variant. For effective tracking and sales reporting, SKUs should be unique and no two product variants should include the same SKU in their details.
source
String
The source or platform where this product was generated from. Corresponds to the first variant.
tags
array
A collection of tags represented as an array of strings.
variants
array
An array of variant key-value hashes. A variant is created for each item in the array. Show child attributes 
curl -X POST https://api.hellotext.com/v1/attribution/products 
 -d name="Sign-Up Form" 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "id": "vxqQJ3Yg",
  "type": "product",
  "brand": "Adidas",
  "categories": [
    "shoes"
  ],
  "collection": [
    "350 v2"
  ],
  "created_at": 1665684173,
  "metadata": {
  },
  "name": "Sign-Up Form",
  "price": {
    "amount": 220.0,
    "converted_amount": 220.0,
    "converted_currency": "EUR",
    "currency": "USD"
  },
  "reference": null,
  "sku": "1234567890",
  "source": null,
  "tags": [
    "Sneakers"
  ],
  "variants": [
    {
      "id": "vxqQJ3Yg",
      "type": "product_variant",
      "created_at": 1665684173,
      "image_url": "https://www.primesneakers.com/products/yeezy-350-v2.jpg",
      "metadata": {
      },
      "name": "Yeezy Boost 350 v2",
      "price": {
        "amount": 220.0,
        "converted_amount": 220.0,
        "converted_currency": "EUR",
        "currency": "USD"
      },
      "product": "vxqQJ3YQ",
      "reference": null,
      "sku": "1234567890",
      "source": null
    },
    "{...}",
    "{...}"
  ]
}

Retrieve a product

Retrieves an existing product. You can find a product by it's id, reference or sku.

 
curl -G https://api.hellotext.com/v1/attribution/products/vxqQJ3Yg 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

Update a product

Updates the specified product with the provided information. You can update a product by it's id, reference or sku.

Parameters
brand
String
Name of the brand of the product.
categories
array
A collection of categories represented as an array of strings.
collection
array
Collection name for products that belongs to a collection.
image_url
URL
An URL pointing to an image of the product. We will download the image and store it on our servers. Please make sure the URL is publicly accessible because we will not be able to access it if it requires authentication.
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
Any name given to the product for reference. This is also the name of the default first variant.
new_variants
array
An array of new variants to add for the product. Each variant is a hash of key-value pairs. Show child attributes
price
hash
A hash representing the price of the product and the associated identifier. It also contains the converted_amount and converted_currency. Show child attributes
reference
String
The product's default variant number or original identifier from the external source that created the product.
sku
String
A case-sensitive identifier for the product's default variant. For effective tracking and sales reporting, SKUs should be unique and no two product variants should include the same SKU in their details.
tags
array
A collection of tags represented as an array of strings.
variants
array
Passing an empty array [] will remove all existing variants from the product. Please make sure to use the new_variants to add new variants for the product. Show child attributes 
curl -X PATCH https://api.hellotext.com/v1/attribution/products/:id 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "id": "vxqQJ3Yg",
  "type": "product",
  "brand": "Adidas",
  "categories": [
    "shoes"
  ],
  "collection": [
    "350 v2"
  ],
  "created_at": 1665684173,
  "metadata": {
  },
  "name": "Yeezy Boost 350 v2",
  "price": {
    "amount": 220.0,
    "converted_amount": 220.0,
    "converted_currency": "EUR",
    "currency": "USD"
  },
  "reference": null,
  "sku": "1234567890",
  "source": null,
  "tags": [
    "Sneakers"
  ],
  "variants": [
    {
      "id": "vxqQJ3Yg",
      "type": "product_variant",
      "created_at": 1665684173,
      "image_url": "https://www.primesneakers.com/products/yeezy-350-v2.jpg",
      "metadata": {
      },
      "name": "Yeezy Boost 350 v2",
      "price": {
        "amount": 220.0,
        "converted_amount": 220.0,
        "converted_currency": "EUR",
        "currency": "USD"
      },
      "product": "vxqQJ3YQ",
      "reference": null,
      "sku": "1234567890",
      "source": null
    },
    "{...}",
    "{...}"
  ]
}

Delete a product

Permanently deletes the specified product. You can delete a product by it's id, reference or sku.

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

List all products

Lists existing products sorting by most recent ones. Pagination parameters are available in lists.

Parameters
ending_before
String
Display results listed before (more recent) than the given id.
limit
integer
Limit how many results to show. Default is 25. Maximum is 100.
starting_after
String
Display results listed after (older) than the given id. 
curl -G https://api.hellotext.com/v1/attribution/products 
 -d limit=5 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "products": [
    {
      "id": "vxqQJ3Yg",
      "type": "product",
      "brand": "Adidas",
      "categories": [
        "shoes"
      ],
      "collection": [
        "350 v2"
      ],
      "created_at": 1665684173,
      "metadata": {
      },
      "name": "Yeezy Boost 350 v2",
      "price": {
        "amount": 220.0,
        "converted_amount": 220.0,
        "converted_currency": "EUR",
        "currency": "USD"
      },
      "reference": null,
      "sku": "1234567890",
      "source": null,
      "tags": [
        "Sneakers"
      ],
      "variants": [
        {
          "id": "vxqQJ3Yg",
          "type": "product_variant",
          "created_at": 1665684173,
          "image_url": "https://www.primesneakers.com/products/yeezy-350-v2.jpg",
          "metadata": {
          },
          "name": "Yeezy Boost 350 v2",
          "price": {
            "amount": 220.0,
            "converted_amount": 220.0,
            "converted_currency": "EUR",
            "currency": "USD"
          },
          "product": "vxqQJ3YQ",
          "reference": null,
          "sku": "1234567890",
          "source": null
        },
        "{...}",
        "{...}"
      ]
    },
    "{...}",
    "{...}"
  ]
}

Product Variants

The Product Variant object represents a specific variation of a product. For example, a product with a size and color can have multiple variants. Each variant can have a different price, SKU or reference.

Variants can be created directly when creating a Product through the variants parameter. Or when updating a product by passing the new_variants parameter.

  • POST

    v1/attribution/products/:product/variants

  • GET

    v1/attribution/variants/:id

  • PATCH

    v1/attribution/variants/:id

  • DELETE

    v1/attribution/variants/:id

The Product Variant object

Attributes
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 to the product variant.
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
Any name given to the product variant for reference.
price
hash
A hash representing the price of the product and the associated identifier. It also contains the converted_amount and converted_currency. Show child attributes
product
product
Identifier of the parent product object that this variant belongs to.
reference
String
The variant number or original identifier from the external source that created the product variant.
sku
String
A case-sensitive identifier for the product variant. For effective tracking and sales reporting, SKUs should be unique and no two product variants should include the same SKU in their details.
source
String
The source or platform where this product variant was generated from. This is always the same as the parent product. 
{
  "id": "vxqQJ3Yg",
  "type": "product_variant",
  "created_at": 1665684173,
  "image_url": "https://www.primesneakers.com/products/yeezy-350-v2.jpg",
  "metadata": {
  },
  "name": "Yeezy Boost 350 v2",
  "price": {
    "amount": 220.0,
    "converted_amount": 220.0,
    "converted_currency": "EUR",
    "currency": "USD"
  },
  "product": "vxqQJ3YQ",
  "reference": null,
  "sku": "1234567890",
  "source": null
}

Create a Product Variant

Creates a new Product Variant.

Make sure to replace the :product with the id, reference or sku of the parent Product. We try to find the parent product firstly by the id, then by the reference and finally by the sku. When no parent product was found, a 404 error will be returned.

Attributes
image_url
URL
A URL pointing to an image of the product variant. We will download the image and store it on our servers. Please make sure the URL is publicly accessible because we will not be able to access it if it requires authentication.
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
Required
Any name given to the product variant for reference.
price
hash
A hash representing the price of the product and the associated identifier. It also contains the converted_amount and converted_currency. Show child attributes
reference
String
The variant number or original identifier from the external source that created the product variant.
sku
String
A case-sensitive identifier for the product variant. For effective tracking and sales reporting, SKUs should be unique and no two product variants should include the same SKU in their details.
source
String
The source or platform where this product variant was generated from. This is always the same as the parent product. 
curl -X POST https://api.hellotext.com/v1/attribution/products/vxqQJ3YQ/variants 
 -d name="Yeezy boost 350 v2" 
 -d sku="1234567890" 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "id": "vxqQJ3Yg",
  "type": "product_variant",
  "created_at": 1665684173,
  "image_url": "https://www.primesneakers.com/products/yeezy-350-v2.jpg",
  "metadata": {
  },
  "name": "Yeezy boost 350 v2",
  "price": {
    "amount": 220.0,
    "converted_amount": 220.0,
    "converted_currency": "EUR",
    "currency": "USD"
  },
  "product": "vxqQJ3YQ",
  "reference": null,
  "sku": "1234567890",
  "source": null
}

Retrieve a Product Variant

Retrieves the details of an existing Product Variant. You can fetch a Product Variant by its id, reference or sku.

 
curl -G https://api.hellotext.com/v1/attribution/variants/vxqQJ3Yg 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

Update a Product Variant

Updates the specified Product Variant. You can update a Product Variant by its id, reference or sku.

Attributes
image_url
URL
A URL pointing to an image of the product variant. We will download the image and store it on our servers. Please make sure the URL is publicly accessible because we will not be able to access it if it requires authentication.
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
Required
Any name given to the product variant for reference.
price
hash
A hash representing the price of the product and the associated identifier. It also contains the converted_amount and converted_currency. Show child attributes
reference
String
The variant number or original identifier from the external source that created the product variant.
sku
String
A case-sensitive identifier for the product variant. For effective tracking and sales reporting, SKUs should be unique and no two product variants should include the same SKU in their details.
source
String
The source or platform where this product variant was generated from. This is always the same as the parent product. 
curl -X PATCH https://api.hellotext.com/v1/attribution/variants/vxqQJ3Yg 
 -d name="Yeezy boost 350 v2" 
 -d sku="5678" 
 -H "Authorization: Bearer ALK_eSMRuwJ2Al..."
{
  "id": "vxqQJ3YQ",
  "type": "product_variant",
  "created_at": 1665684173,
  "image_url": "https://www.primesneakers.com/products/yeezy-350-v2.jpg",
  "metadata": {
  },
  "name": "Yeezy boost 350 v2",
  "price": {
    "amount": 220.0,
    "converted_amount": 220.0,
    "converted_currency": "EUR",
    "currency": "USD"
  },
  "product": "vxqQJ3YQ",
  "reference": null,
  "sku": "5678",
  "source": null
}

Destroy a Product Variant

Destroys the specified Product Variant. You can destroy a Product Variant by its id, reference or sku.

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

Refunds

Refund objects represent refunds that you can use to track actions through its lifecycle such as refund.requested and refund.received.

Refund objects act as logical groups where you can group multiple actions to the same object for better reporting.

 
  POST /v1/attribution/refunds
   GET /v1/attribution/refunds/:id
 PATCH /v1/attribution/refunds/:id
DELETE /v1/attribution/refunds/:id
   GET /v1/attribution/refunds

The refund object

Attributes
id
string
Unique identifier of the refund object.
type
string
Type of object. This is always refund.
created_at
epoch
Date of creation of the refund object.
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
Identifier of the associated profile object that this refund belongs to.
reference
string
The refund number or original identifier from the external source that created the refund.
refundable
hash
The refunded object. Hash representing the associated order or product refunded. This attribute is optional and by default its value is set to null.
source
string
The identifier of the platform where the refund was created from.
total
hash
A hash representing the total and converted total of the refund. Show child attributes 
{
  "id": "w83Pj4PY",
  "type": "refund",
  "created_at": 1665684173
  "metadata": {},
  "profile": null,
  "reference": null,
  "refundable": {
    "id": "ro4a731w",
    "type": "order",
    "amount": "199.95",
    "created_at": 1665684173,
    "currency": "USD",
    "metadata": {}
  },
  "source": null,
  "total": {
    "amount": "199.95",
    "converted_amount": "199.95",
    "converted_currency": "EUR",
    "currency": "USD",
  }
}

Create a refund

Creates a new refund.

Parameters
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
Identifier of the order object associated to this refund. The order will be set as the refundable object.
product
string
Identifier of the product object associated to this refund. The product will be set as the refundable object.
profile
string
Identifier of the associated profile object that this refund belongs to.
reference
string
The refund number or original identifier from the external source that created the refund.
source
string
The identifier of the platform where the refund was created from.
total
hash
A hash representing the total and converted total of the refund. When unspecified, the total will be set from the total of the order object, or from the price of the product object. Show child attributes 
curl https://api.hellotext.com/v1/attribution/refunds \
  -d amount=19.90 \
  -d order=ro4a731w \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "id": "w83Pj4PY",
  "type": "refund",
  "created_at": 1665684173
  "metadata": {},
  "profile": null,
  "reference": null,
  "refundable": {
    "id": "ro4a731w",
    "type": "order",
    "amount": "199.95",
    "created_at": 1665684173,
    "currency": "USD",
    "metadata": {}
  },
  "source": null,
  "total": {
    "amount": "199.95",
    "converted_amount": "199.95",
    "converted_currency": "EUR",
    "currency": "USD",
  }
}

Retrieve a refund

Retrieves an existing refund.

 
curl -G https://api.hellotext.com/v1/attribution/refunds/w83Pj4PY \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

Update a refund

Updates the specified refund with the provided information.

Parameters
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
Identifier of the order object associated to this refund. The order will be set as the refundable object.
product
string
Identifier of the product object associated to this refund. The product will be set as the refundable object.
profile
string
Identifier of the associated profile object that this refund belongs to.
reference
string
The refund number or original identifier from the external source that created the refund.
source
string
The identifier of the platform where the refund was created from.
total
hash
A hash representing the total and converted total of the refund. When unspecified, the total will be set from the total of the order object, or from the price of the product object. 
curl https://api.hellotext.com/v1/attribution/refunds/w83Pj4PY \
  -d amount=24.90 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "id": "w83Pj4PY",
  "type": "refund",
  "created_at": 1665684173
  "metadata": {},
  "profile": null,
  "reference": null,
  "refundable": {
    "id": "ro4a731w",
    "type": "order",
    "amount": "199.95",
    "created_at": 1665684173,
    "currency": "USD",
    "metadata": {}
  },
  "source": null,
  "total": {
    "amount": "199.95",
    "converted_amount": "199.95",
    "converted_currency": "EUR",
    "currency": "USD",
  }
}

Delete a refund

Permanently deletes the specified refund.

 
curl -X DELETE https://api.hellotext.com/v1/attribution/refunds/w83Pj4PY \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "id": "w83Pj4PY",
  "type": "refund",
  "deleted": true
}

List all refunds

Lists existing refunds sorting by most recent ones. Pagination parameters are available in lists.

Parameters
starting_after
string
Display results listed after (older) than the given id.
ending_before
string
Display results listed before (more recent) than the given id.
limit
integer
Limit how many results to show. Default is 25. Maximum is 100. 
curl -G https://api.hellotext.com/v1/attribution/refunds \
  -d limit=5 \
  -H "Authorization: Bearer ALK_eSMRuwJ2Al..."

{
  "refunds": [
    {
      "id": "w83Pj4PY",
      "type": "refund",
      "created_at": 1665684173
      "metadata": {},
      "profile": null,
      "reference": null,
      "refundable": {
        "id": "ro4a731w",
        "type": "order",
        "amount": "199.95",
        "created_at": 1665684173,
        "currency": "USD",
        "metadata": {}
      },
      "source": null,
      "total": {
        "amount": "199.95",
        "converted_amount": "199.95",
        "converted_currency": "EUR",
        "currency": "USD",
      }
    },
    {...},
    {...}
  ]
}

Sessions

Sessions are unique identifiers generated when visitors click on short links and attached to the destination URL as a GET parameter called hello_session. You can think of a session as sharing the same known meaning from web browsers: it represents an active visitor browser and is device specific.

Tracking events specifying the session identifier will also keep an automatic association to the customer profile who clicked on the short link, aggregating the events to his history of activities and to the reporting of the campaign or journey where the message with the short link was present.

When tracking client-side events with the Hellotext.js library, there is no need to explicitly specify the session identifier as the library will take care of it behind the scenes.

To improve security and privacy we discourage disclosing the identifier of the profile directly on the browser. Because of this, the client-side Hellotext.js library only accepts to track events specifying a session and not to a profile directly.

It is possible to track events for non-identified visitors too. The Hellotext.js library creates a new session identifier for every new visitor when it does not find it defined as a parameter. You can store this session identifier, and later attach the profile when it becomes known, for example when the visitor logins into the store, places an order, or subscribes entering his phone number.

 
  PATCH /v1/sessions/:id

Attach session

Once the profile is known, attach it to the session so all its events tracked become part of his history of activities.

If you also want to change the session to a different profile, set the new profile identifier in the profile parameter and the session will be assigned to the new profile.

All carts associated with a session will be assigned to the profile you attach the session to.

Parameters
profile
string
Required
The profile to assign the session and its tracked events to.
hellotext
  • Stay ahead in eCommerce marketing.
  • Sign up for Hellotext insights and updates.
© 2024 Hellotext
  • United States
  • English