JavaScript API

JavaScript API

This basic integration uses a Javascript snippet, a block of code inserted into your website. It’s a low-impact way to send data to Wooxy — through your users’ web browsers. While an API integration is more flexible, this is a really quick way to get started.

Installation

To install our JS API, you need to take the following steps:

  1. Generate and get JS code snippet
  2. Download and extract the Worker File from the archive and add it to the root directory of your website.
  3. Include JS code snippet on every page in your app immediately before the closing </body> tag.
  4. Properly identify your user.
  5. Call JS API methods to manage your user data.
  6. IMPORTANT Many JS API methods work only if the contact is already in the Contact List.

IMPORTANT Include this snippet on every page in your app immediately before the closing </body> tag to initialize JS API and identify your user.

                <script type="text/javascript" src="//js.wooxy.com/js/v1/JS_SCRIPT_ID.js">
</script>
            
IMPORTANT Here are some things to know before you begin using JS API.
We only track activity for users registered on your website after the js script is called.
We do not track anonymous or unregistered user activity.
To update an existing user’s variables, send the js script call again. You must include their identification and any new attribute values.
If the variables already exist in their profile, we’ll overwrite them.
If there are any new variables included in the call, we’ll add them to the profile.
We do not edit the user’s identification method if the contact already adds to the contact list.

IMPORTANT Do not send more than 10 concurrent API requests.

User Identification

To identify your user, you need to provide minimum one unique user identificator.
userId | email | phoneNumber

You should make JS API calls after identifying your user, so that you can associate events with a person in your Contact List.

WARNING Minimum one unique user identification (userId | email | phoneNumber ) is required.

IMPORTANT Include this snippet on every page in your app immediately before the closing </body> tag to initialize JS API and identify your user.

                <script type="text/javascript" src="//js.wooxy.com/js/v1/JS_SCRIPT_ID.js>
</script>
<script 
    var contact = new _wooxyContact('user@example.com');
</script>
            
Parameters
new _wooxyContact();
'required'
Call Web Push Notification One-click Subscription Prompt on any page or by user action.
contact
'required'
Minimum one unique user identification (userId | email | phoneNumber) is required to identify and match the user in the Contact List.

Add New Contact

To add a contact to the Contact List you need properly identify your user and fire an event on your web page

IMPORTANT Include this snippet on every page in your app immediately before the closing </body> tag to initialize JS API and identify your user.

                <script type="text/javascript" src="//js.wooxy.com/js/v1/JS_SCRIPT_ID.js>
</script>
<script type="text/javascript">
    var contact = new _wooxyContact('USER_UNIQUE_IDENTIFIER');
</script>
            

Call Contact Creation API method and add additional properties to your new contact in case of need.

                <script type="text/javascript">
    contact.Add({    
        name: "John Doe",   
        email: "user@example.com",
        phoneNumber: "+15555555",
        userId: "myUserId",
        active: true,
        emailSubscribe: true,
        smsSubscribe: true,
        viberSubscribe: true,
        firstName: "John",
        lastName: "Doe",
        contactBirthday: "YYYY-MM-DD",
        contactLanguage: "en",
        contactGender: "female",
        contactTimezone: "Europe/Tallinn",
        contactScore: 100,
        avatarLink: "https://img.wooxy.com/g/06c38b4568.jpg",
        facebookLink: "https://facebook.com/wooxy.com",
        instagramLink: "https://instagram.com/wooxy",
        linkedInLink: "https://linkedin.com/company/wooxy",
        twitterLink: "https://twitter.com/wooxy",
        tiktokLink: "https://tiktok.com/wooxy",
        sourceId: "Source_ID_from_Wooxy",
        customerSourceId: "Customer_Source_ID_From_Your_Platform",
        cac: {
            value:      2.05,
            currency:   "USD",
        },
        variables: [
            {name: "stringVariableName", value: "newVariableValue"},
            {name: "dateVariableName", value: "YYYY-MM-DD"}
        ],
    });
</script>
            
Parameters
contact   
'required'
An array of contact information.
name   
'optional'
The optional display name to use for the recipient
email   
'optional'
Contact’s email address.
phoneNumber   
'optional'
IMPORTANT: should be valid E.164 phone number format.
userId   
'optional' 
Contact’s unique user ID from your platform to enable management of the contact in the list based on it.
active   
'optional'
You can set if the contact is enabled contact list or not.   
The default value is false (disabled).
true   
'optional'
Contact enabled. Contact can receive communication from enabled channels.
false   
'default'
Contact disabled. No communications will be sent to this contact.
emailSubscribe   
'optional'
You can set if the contact is subscribed to receiving emails or not.   
The default value is false (unsubscribed).
true   
'optional'
Subscribe to contact emails
false   
'default'
Unsubscribe contact from emails
smsSubscribe   
'optional'
You can set if the contact is subscribed to receiving SMS or not.   
The default value is false (unsubscribed).
true   
'optional'
Subscribe Contact to SMS
false   
'default'
Unsubscribe contact from SMS
firstName   
'optional'
Contact’s first name
lastName   
'optional'
Contact’s last name
contactBirthday   
'optional'
Contact’s birth date in ENUM_DATE (YYYY-MM-DD) format
contactLanguage   
'optional'
Contact’s locale in ISO 639-1 format
contactGender   
'optional'
Contact’s gender in ISO/IEC 5218 format
0Not known
1Male
2Female
9Not applicable
contactTimezone   
'optional'
Contact’s timezone in ISO 8601 format
contactScore   
'optional'
Contact Score
avatarLink   
'optional'
Link to contact’s avatar image.
facebookLink   
'optional'
Link to contact’s Facebook profile.
instagramLink   
'optional'
Link to contact’s Instagram profile.
linkedInLink   
'optional'
Link to contact’s LinkedIn profile.
twitterLink   
'optional'
Link to contact’s Twitter profile.
tiktokLink   
'optional'
Link to contact’s TikTok profile.
variables   
'optional'
An array of contact variables and their values.
name   
'required'
Variable name in lowerCamelCase format   
WARNING: Please use only Latin lowerCamelCase format. No numbers or other symbols are allowed.
value   
'required'
Variable value in 'ENUM_STRING' or 'ENUM_DATE' (YYYY-MM-DD) format correspondingly
sourceId   
'optional'
Contact’s unique source ID from the Wooxy platform
customerSourceId   
'optional'
Contact’s unique source ID from your system to synchronize two sides
cac   
'optional'
value   
'required'
CAC value in 'ENUM_STRING' format correspondingly
currency   
'required'
(EUR, USD)   
WARNING: Please use only the Latin uppercase format. No numbers or other symbols are allowed.

Update Contact Data

To update contact data in the Contact List, you need to properly identify your user and fire an update event on your web page.

IMPORTANT Include this snippet on every page in your app immediately before the closing </body> tag to initialize JS API and identify your user.

                <script type="text/javascript" src="//js.wooxy.com/js/v1/JS_SCRIPT_ID.js>
</script>
<script type="text/javascript">
    var contact = new _wooxyContact('USER_UNIQUE_IDENTIFIER');
</script>
            

Call Contact Update API method and add/update properties of your contact in case of need.

                <script type="text/javascript">
    contact.update({    
        name: "John Doe",   
        email: "user@example.com",
        phoneNumber: "+15555555",
        userId: "myUserId",
        active: true,
        emailSubscribe: true,
        smsSubscribe: true,
        viberSubscribe: true,
        firstName: "John",
        lastName: "Doe",
        contactBirthday: "YYYY-MM-DD",
        contactLanguage: "en",
        contactGender: "female",
        contactTimezone: "Europe/Tallinn",
        contactScore: 100,
        avatarLink: "https://img.wooxy.com/g/06c38b4568.jpg",
        facebookLink: "https://facebook.com/wooxy.com",
        instagramLink: "https://instagram.com/wooxy",
        linkedInLink: "https://linkedin.com/company/wooxy",
        twitterLink: "https://twitter.com/wooxy",
        tiktokLink: "https://tiktok.com/wooxy",
        sourceId: "Source_ID_from_Wooxy",
        customerSourceId: "Customer_Source_ID_From_Your_Platform",
        cac: {
            value:      2.05,
            currency:   "USD",
        },
        variables: [
            {name: "stringVariableName", value: "newVariableValue"},
            {name: "dateVariableName", value: "YYYY-MM-DD"}
        ],
    });
</script>
            
Parameters
USER_UNIQUE_IDENTIFIER
'required'
The 'email' address, 'userId' or 'phoneNumber' of the recipient stored in the DefaultContactList.
contact   
'required'
An array of contact information.
name   
'optional'
The optional display name to use for the recipient
email   
'optional'
Contact’s email address.
phoneNumber   
'optional'
IMPORTANT: should be valid E.164 phone number format.
userId   
'optional' 
Contact’s unique user ID from your platform to enable management of the contact in the list based on it.
active   
'optional'
You can set if the contact is enabled contact list or not.   
The default value is false (disabled).
true   
'optional'
Contact enabled. Contact can receive communication from enabled channels.
false   
'default'
Contact disabled. No communications will be sent to this contact.
emailSubscribe   
'optional'
You can set if the contact is subscribed to receiving emails or not.   
The default value is false (unsubscribed).
true   
'optional'
Subscribe to contact emails
false   
'default'
Unsubscribe contact from emails
smsSubscribe   
'optional'
You can set if the contact is subscribed to receiving SMS or not.   
The default value is false (unsubscribed).
true   
'optional'
Subscribe Contact to SMS
false   
'default'
Unsubscribe contact from SMS
firstName   
'optional'
Contact’s first name
lastName   
'optional'
Contact’s last name
contactBirthday   
'optional'
Contact’s birth date in ENUM_DATE (YYYY-MM-DD) format
contactLanguage   
'optional'
Contact’s locale in ISO 639-1 format
contactGender   
'optional'
Contact’s gender in ISO/IEC 5218 format
0Not known
1Male
2Female
9Not applicable
contactTimezone   
'optional'
Contact’s timezone in ISO 8601 format
contactScore   
'optional'
Contact Score
avatarLink   
'optional'
Link to contact’s avatar image.
facebookLink   
'optional'
Link to contact’s Facebook profile.
instagramLink   
'optional'
Link to contact’s Instagram profile.
linkedInLink   
'optional'
Link to contact’s LinkedIn profile.
twitterLink   
'optional'
Link to contact’s Twitter profile.
tiktokLink   
'optional'
Link to contact’s TikTok profile.
variables   
'optional'
An array of contact variables and their values.
name   
'required'
Variable name in lowerCamelCase format   
WARNING: Please use only Latin lowerCamelCase format. No numbers or other symbols are allowed.
value   
'required'
Variable value in 'ENUM_STRING' or 'ENUM_DATE' (YYYY-MM-DD) format correspondingly
sourceId   
'optional'
Contact’s unique source ID from the Wooxy platform
customerSourceId   
'optional'
Contact’s unique source ID from your system to synchronize two sides
cac   
'optional'
value   
'required'
CAC value in 'ENUM_STRING' format correspondingly
currency   
'required'
(EUR, USD)   
WARNING: Please use only the Latin uppercase format. No numbers or other symbols are allowed.

Fire Event

To send a user event to Wooxy you need to properly identify your user and fire an event on your web page.

IMPORTANT Include this snippet on every page in your app, immediately before the closing </body> tag to initialize JS API and identify your user.

                <script type="text/javascript" src="//js.wooxy.com/js/v1/JS_SCRIPT_ID.js>
</script>
<script type="text/javascript">
    var contact = new _wooxyContact('USER_UNIQUE_IDENTIFIER');
</script>
            

Initialize the event object and call the “Fire Event” API method.

                <script type="text/javascript">
    var event = new _wooxyEvent(
        '{{YOUR_REGISTERED_EVENT_ID or EVENT_NAME}}', 
        '{{value}}', 
        '{{USD}}'
    );

   event.setVariables([
       {'name':'newVariableName1','value':'newVariableValue1'},
       {'name':'newVariableName2','value':'YYYY-MM-DD'}
   ]);

    event.addVariable('newVariableName3','newVariableValue3');

    contact.FireEvent(event);
</script>
            
Parameters
USER_UNIQUE_IDENTIFIER
'required'
The 'email' address, 'userId' or 'phoneNumber' of the recipient stored in the DefaultContactList.
new _wooxyEvent();
'required'
Create an event object and add optional attributes in case of need.
FireEvent();
'required'
Fire the event to send the data to Wooxy.
customEvent
'required'
Unique eventId or eventName that is already registered in the Wooxy system.
eventValue
'required'
Value in 'FLOAT' or 'INTEGRER' format correspondingly. DOT divider.
eventCurrency
'optional'
Only EUR or USD. IMPORTANT Latin uppercase format allowed. No numbers or other symbols are allowed.
addVariable()
'optional'
You can add a custom variable, which will be placed in the template that we host.
setVariables()
'optional'

You can add an associative array of custom variables which will be placed in your template which we host.

IMPORTANT Variables will be available only in Workflows.

Please, take in account variables usage priorities is case of conflicting variables:
 

  • First Priority: Variable from API request;
  • Second Priority: Variable from the Component Custom Variables;
  • Third Priority: Variable from the contact list.

Web Push Prompt

To Call Web Push Notification One-click Subscription Prompt on your website, you need to properly identify your user and fire an event on your web page.

IMPORTANT Include this snippet on every page in your app immediately before the closing </body> tag to initialize JS API and identify your user.

                <script type="text/javascript" src="//js.wooxy.com/js/v1/JS_SCRIPT_ID.js>
</script>
<script type="text/javascript">
    var contact = new _wooxyContact('USER_UNIQUE_IDENTIFIER');
</script>
            

Call the “Show web push subscription prompt” modal API method.

                <script type="text/javascript">
    contact.ShowPushPrompt();
</script>
            
Parameters
USER_UNIQUE_IDENTIFIER
'required'
The 'email' address, 'userId' or 'phoneNumber' of the recipient stored in the DefaultContactList.
ShowPushPrompt();
'required'
Call Web Push Notification One-click Subscription Prompt on any page or by user action.

Telegram Link

To generate Telegram bot one-click subscription link on your website, you need to properly identify your user and fire an event on your web page.

IMPORTANT Include this snippet on every page in your app immediately before the closing </body> tag to initialize JS API and identify your user.

                <script type="text/javascript" src="//js.wooxy.com/js/v1/JS_SCRIPT_ID.js>
</script>
<script type="text/javascript">
    var contact = new _wooxyContact('USER_UNIQUE_IDENTIFIER');
</script>
            

Call the “Generate telegram subscription link” API method.

                <script type="text/javascript">
    contact.CreateTelegramSubscriptionLink(
        '{{domElementId}}', 
        '{{telegramBotId}}'
    );
</script>
            
Parameters
USER_UNIQUE_IDENTIFIER 
'required'
The 'email' address, 'userId' or 'phoneNumber' of the recipient stored in the DefaultContactList.
CreateTelegramSubscriptionLink(); 
'required'
Call Telegram bot One-click Subscription Prompt on any page or by user action.
domElementId; 
'required'
HTML element ID where the unique Telegram or subscription link should be generated.
telegramBotId; 
'required'
Telegram Bot ID, which you can get from the Wooxy Telegram integration page.
IMPORTANT The function returns a Promise object and runs asynchronously
Your button should have a specific element ID <a id="some-url-id">Click here to Subscribe to Telegram</a>, where you need to generate a Telegram Bot subscription link. Learn more by link.
Need Help?

Our technical support team will be happy to help with your integration. They are at your disposal 24/7.

Just send us a line by following email address with the information where you have been stuck so we could help faster: support@wooxy.com.

Need Help? Contact us