Totango Destination

Destination Info
Connection Modes
Device-mode Cloud-mode
Web Web
Mobile Mobile
Server Server

Our Totango destination code is all open-source on GitHub if you want to check it out: JavaScript, Server.

Getting Started

To get started with Totango and Segment, toggle Totango on in your Segment destinations and add your Service ID, which you can find in your Totango settings.

Once you’ve done that, those new settings will propagate to our CDN (that usually takes around 45 minutes) and Totango will be live on your site! Since Totango is all about identified users, the next thing you’ll want to do is add a few API calls with exactly the information Totango needs. We’ll show you how..

Note: As part of setup, you should know the user and call identify before the group call. Remember that every page and track call that you want to show up in Totango must be tied to a groupId (Totango calls this Account ID). , however.

For our client-side Javascript library (Analytics.js) that means you need to call group at least once with a groupId and we will cache it and attach it to future calls to other methods.

For server-side and mobile libraries you must include context.groupId in every call you want to be sent through to Totango so they can connect the dots between a call made to Segment and an account in their system.


Totango also needs to know what “account” the user belongs to. To record this, you’d use our group method. Group also takes a unique ID (for the group this time!) and a dictionary of properties about the group. It looks like this:

A call to group is required before any track calls will be sent to Totango.'sjsj2hdj2', {
  name: 'Initech',
  website: ''

Making a call like that will add the current user to the group, which maps directly to Totango’s “accounts”.

You should always call group after your call to identify, so that we know which user you want to associate with the group. To learn more about how group works, check out our Group docs.


Totango allows you to split your application into functional sections known as modules. By default, Totango pulls this module out of the users current URL. You can customize this behavior by using our page method. You can pass category as a property to page and we’ll set that as the module in Totango.

page takes the category of the page, the name of the page and any optional properties you want to associate with the pageview. The page call is included by default in your snippet, since it’s a required call. Modify the page call inside the snippet or move it elsewhere, but don’t delete it.

It looks like this:

// Names and categorizes the page... sets the totango module to "Blog"'Blog', '15,000 Ways to Increase Conversion');

You can label as many categories / modules as you need, but as a best practice you’ll probably want to have around 5 for a small – medium sized app to 20 for a very large web-application.


The first thing Totango needs to know is “who is the user browsing your site?” You record this with our identify method. Identify takes the unique ID of a user and any traits you know about them. It looks like this:

analytics.identify('29ej29d', {
  email: '',
  name: 'Lawrence Drywall',
  age: 42

To learn more about how identify works, check out our Identify docs. For example, email and name are two of our special traits that we recognize semantically.

If you’re sending data using the server-side or mobile libraries, you’ll need to include context.groupId. Check out the server-side section to see how.

Special Properties

Totango recognizes a few special properties for accounts that mean very specific things. For example, an account’s plan indicates whether they are paying you or not. Here are the special properties for the group method that Segment will recognize and translate for you automatically:

created Date or String The date when the account was first created. We will automatically change this from created to 'Create Date' for the Totango API, but you should send it to us as created. If you don’t provide this, Totango will default to the current date.
plan String, optional The “Free” or “Paying” plan of the account. You can set up extra types of plans in your Totango settings if “Free” and “Paying” don’t suit your needs. If you don’t provide this, we’ll default it to "Free".

To use the rest of the Totango’s special properties, just pass them exactly like you would normally to Totango and we’ll send them straight through!


Totango also lets you record any events a user triggers in your interface. To do that with Segment you’d use our track method. If you’re just starting out with events, we usually recommend recording 5-10 of your business’s most important events. You can always add more later!

track takes the name of the event and any optional properties you want to associate with the event. If you’d like to add a category to your track calls in addition to your page calls, you can add them as properties. It looks like this:

analytics.track('Completed Purchase', {
  revenue: 42.99,
  shippingMethod: '2-day',
  category: 'Conversion'

To learn more about how track works check out our Track docs. For example, revenue is a special property that lets you semantically describe how much money you’re making.

If you’re sending data using the server-side or mobile libraries, you’ll need to include context.groupId. Check out the troubleshooting section to see how.


Server-side Methods Require Group ID

Totango requires groupId on every identify, page and track call, so you’ll need to pass it using context.groupId.

Here’s a node identify example to get you started:

  userId: '29ej29d',
  traits: {
    email: '',
    name: 'Lawrence Drywall',
    age: 42
  context: {
    groupId: 'sjsj2hdj2'


You can send computed traits and audiences generated using Engage to this destination as a user property. To learn more about Engage, schedule a demo.

For user-property destinations, an identify call is sent to the destination for each user being added and removed. The property name is the snake_cased version of the audience name, with a true/false value to indicate membership. For example, when a user first completes an order in the last 30 days, Engage sends an Identify call with the property order_completed_last_30days: true. When the user no longer satisfies this condition (for example, it’s been more than 30 days since their last order), Engage sets that value to false.

When you first create an audience, Engage sends an Identify call for every user in that audience. Later audience syncs only send updates for users whose membership has changed since the last sync.

Real-time to batch destination sync frequency

Real-time audience syncs to Totango may take six or more hours for the initial sync to complete. Upon completion, a sync frequency of two to three hours is expected.


Segment lets you change these destination settings from the Segment app without having to touch any code.

Setting Description
Disable the Totango Heartbeat boolean, defaults to FALSE .

By default Totango’s Javascript pings its servers once a minute to see if the user has left the page. If you don’t want that to happen, enable this setting.
select. What region should data be sent to. Currently applies only for web device-mode integration and not cloud-mode integration. Please note, the region should match your settings in Totango.
Service ID
string. You can find your Service ID under Settings > Developer Console in Totango.
Track Categorized Pages to Totango boolean, defaults to TRUE .

This will track events to Totango for page method calls that have a category associated with them. For example page('Docs', 'Index') would translate to Viewed Docs Index Page.
Track Named Pages to Totango boolean, defaults to TRUE .

This will track events to Totango for page method calls that have a name associated with them. For example page('Signup') would translate to Viewed Signup Page.

This page was last modified: 15 Jul 2022

Get started with Segment

Segment is the easiest way to integrate your websites & mobile apps data to over 300 analytics and growth tools.
Create free account