Overview

contacts.js is a library used to capture contact information quickly and easily. It focuses on simplicity and ease of use for both client-side and server-side usage.

You may choose to save a contacts phone number only, or you may include further contact info as well:

voxie.capture("+15551231234");

voxie.capture("+15551231234");

voxie.capture("+15551231234", {
  firstName: "John",
  lastName: "Doe",
  // tags and custom attribute keys must be lowercase
  tags: ["purchased", "online"],
  customAttributes: {
    last_purchase_sku: "vxe123",
    last_product_viewed_sku: "vxe456",
  },
  subscriptionStatuses: {
    marketing: "opt_in"
  }
});

voxie.capture("+15551231234", {
  firstName: "John",
  lastName: "Doe",
  // tags and custom attribute keys must be lowercase
  tags: ["purchased", "online"],
  customAttributes: {
    last_purchase_sku: "vxe123",
    last_product_viewed_sku: "vxe456",
  },
  subscriptionStatuses: {
    marketing: "opt_in"
  }
});

Installation via package manager

We're big fans of pnpm, but you can get started with any package manager of choice.

# npm
npm install @voxie/contacts.js

# yarn
yarn add @voxie/contacts.js

# pnpm
pnpm add @voxie/contacts.js

Installation via CDN

We provide a CDN option for client-side usage via unpkg so that you can select your preferred version as well. We recommend using the latest major version.

<html>
  <head>
    <script src="https://unpkg.com/@voxie/contacts.js@0/dist/contacts.js"></script>
  </head>
</html>

Initialization

If you have installed contacts.js as a package:

import { Voxie } from "@voxie/contacts.js";

import { Voxie } from "@voxie/contacts.js";

If you have injected via script tag, the Voxie class will be available without the use of an import. You will need an associated connection to use the library.

The following recipe shows how to create a connection and generate a public key and public secret.

🤖

Use the connections data plane

Open Recipe

Once you have your key and secret, you can initialize the library by passing in your key and secret. You can then start capturing contact data.

Capture

const voxie = await Voxie.init({
  publicKey: "<YOUR_WRITE_KEY>",
  publicSecret: "<YOUR_SECRET_KEY>",
});

voxie.capture("+15551231234");

const voxie = await Voxie.init({
  publicKey: "<YOUR_WRITE_KEY>",
  publicSecret: "<YOUR_SECRET_KEY>",
});

voxie.capture("+15551231234");

Usage across frameworks and vanilla TypeScript or JavaScript will be similar. An example of usage for a vanilla client side implementation is as follows.

Create your HTML form.
Attach an event listener for your form.
Initialize the library.
Capture contact information in event handler for your form by calling voxie.capture() with phone number and optional contact info.

You can achieve a similar process in common frameworks like React or Vue. Here are some examples.

<head>
  <!-- inject contacts library inside head tag-->
  <script src="https://unpkg.com/@voxie/contacts.js@0/dist/contacts.js"></script>
</head>
<body>
  <form name="signup">
    <label>
      Phone:
      <input name="phone" type="tel"/>
    </label>
    <input type="submit"/>
  </form>

  <script>
    const form = document.forms.myForm;

    // attach event handler
    form.addEventListener("submit", async (e) => {
      e.preventDefault();
      // initialize contacts library
      const voxie = await Voxie.init({
        publicKey: "<YOUR_WRITE_KEY>",
        publicSecret: "<YOUR_SECRET_KEY>",
      });

      const phone = form.phone.value;
      // capture contact data
      voxie.capture(phone);
    });
  </script>
</body>

import { Voxie } from "@voxie/contacts.js";

// we can export this instance to share with rest of our codebase.
export const voxie = await Voxie.init({
  publicKey: "<YOUR_WRITE_KEY>",
  publicSecret: "<YOUR_SECRET_KEY>",
});

const App = () => (
  // (inlined for brevity) - pass telephone input to voxie capture
  <form
    onSubmit={(e) => {
      e.preventDefault();
      const phone = e.target.phone.value;
      voxie.capture(phone);
    }}
  >
    <label>
      Phone:
      <input name="phone" type="tel" />
    </label>
    <input type="submit" value="Submit" />
  </form>
);

<template>
  <!-- (inlined for brevity) - pass telephone input to voxie capture -->
  <form @submit.prevent="capture($event)">
    <label>
      Phone:
      <input name="phone" type="tel" />
    </label>
    <input type="submit" value="Submit" />
  </form>
</template>

<script>
  import { defineComponent } from "vue";

  export default defineComponent({
    setup() {
      function capture(event) {
        const voxie = await Voxie.init({
			    publicKey: "<YOUR_WRITE_KEY>",
			    publicSecret: "<YOUR_SECRET_KEY>",
  			});
        const phone = event.target.phone.value;
        voxie.capture(phone);
      }

      return {
        capture,
      };
    },
  });
</script>

Form Sharing

You can also share existing form data with Voxie on submit.

<head>
  <!-- inject contacts library inside head tag-->
  <script src="https://unpkg.com/@voxie/contacts.js@0/dist/contacts.js"></script>
</head>
<body>
  <form id="signup" name="signup" method="POST" action="https://example.com/signup">
    <label>
      Phone:
      <input name="phone" type="tel"/>
    </label>
    <input type="submit"/>
  </form>

  <script defer>
    (async function () {
        window.voxie = await Voxie.init({
            publicKeyId: '2N3sKzrWtxKx0iDIvzm40XlOcrK',
            publicSecret: '4VXAMTKDzld36S19det5Ixg22xBhUlXfETb6EPoE4XfR4gtZyTqlqPQlaqvKHvLRaN3A9zmnTveTwYAVvSqt0b3PDv1wS3saWcXzQhB6LilS',
            connectBaseUri: 'https://connect.voxie.com',
        });
        window.voxie.share(
          document.getElementById('signup'),
          { phone: 'phone' },
          {
            customAttributes: { signup_date: (new Date().toLocaleDateString()) }
          }
        );
    })();
  </script>
</body>