API Reference

init()

Voxie.init() initializes the library with a connection's public key ID and public secret. It returns a Voxie instance synchronously.

The optional connectBaseUri property overrides the Connections service URL. Most integrations should use the default value.

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

const voxie = Voxie.init({
  publicKeyId: "<YOUR_PUBLIC_KEY_ID>",
  publicSecret: "<YOUR_PUBLIC_SECRET>",
});

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

const voxie = Voxie.init({
  publicKeyId: "<YOUR_PUBLIC_KEY_ID>",
  publicSecret: "<YOUR_PUBLIC_SECRET>",
});

Returns: Voxie

capture()

capture() sends a contact to Voxie. The phone number is required; all contact data in the second argument is optional.

U.S. national numbers and international numbers are accepted and normalized to E.164 format. The promise resolves to false if the number is not possible or the request cannot be sent.

const captured = await voxie.capture("+15551231234", {
  firstName: "John",
  lastName: "Doe",
  email: "[email protected]",
  timeZone: "America/Los_Angeles",
  // tags and custom attribute keys must be lowercase
  tags: ["purchased", "online"],
  customAttributes: {
    last_purchase_sku: "vxe123",
    last_product_viewed_sku: "vxe456",
  },
  subscriptionStatuses: {
    transactional: "opt_in",
  },
  subscriptionConsentRequests: {
    marketing: "opt_in",
  },
  groupId: "preferred-location",
});

const captured = await voxie.capture("+15551231234", {
  firstName: "John",
  lastName: "Doe",
  email: "[email protected]",
  timeZone: "America/Los_Angeles",
  // tags and custom attribute keys must be lowercase
  tags: ["purchased", "online"],
  customAttributes: {
    last_purchase_sku: "vxe123",
    last_product_viewed_sku: "vxe456",
  },
  subscriptionStatuses: {
    transactional: "opt_in",
  },
  subscriptionConsentRequests: {
    marketing: "opt_in",
  },
  groupId: "preferred-location",
});

tags accepts a read-only array or set. customAttributes, subscriptionStatuses, and subscriptionConsentRequests accept a read-only object or map. Tags must be unique, and tags and custom attribute keys must be lowercase.

Subscription status and consent request keys may be marketing or transactional, and their values may be opt_in or opt_out. The same subscription type cannot be included in both subscriptionStatuses and subscriptionConsentRequests in one capture.

Returns: Promise<boolean>

share()

share() attaches a submit listener to an existing form and sends its contact information to Voxie. The form element and the name of its phone field are required. First name, last name, and email field names are optional.

The optional third argument applies the same tags, custom attributes, subscription statuses, subscription consent requests, and group ID to every contact submitted through the form.

const form = document.getElementById("purchase") as HTMLFormElement;

voxie.share(
  form,
  {
    // values are field names within the form
    phone: "phone",
    firstName: "first-name",
    lastName: "last-name",
    email: "email",
  },
  {
    // tags and custom attribute keys must be lowercase
    tags: ["purchased", "online"],
    customAttributes: {
      last_purchase_sku: "vxe123",
      last_product_viewed_sku: "vxe456",
    },
    subscriptionConsentRequests: {
      marketing: "opt_in",
    },
    groupId: "preferred-location",
  }
);

Returns: void

popUp()

popUp() adds a contact capture pop-up to the current page. Both the display name and terms text are required.

const popUp = voxie.popUp({
  name: "Voxie",
  terms: "By signing up, you agree to receive messages.",
});

popUp.auto();

The returned PopUp can be controlled with open(), close(), toggle(), or auto(delay). The optional delay is measured in milliseconds; without one, auto() opens the pop-up after 1.5 seconds.

Returns: PopUp