Totango Destination

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. Not sure which modules to use? Check out Totango’s Best Practices guide.


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 through Segment Personas to this destination as a user property. To learn more about Personas, contact us for a demo.

For user-property destinations, an identify call will be sent to the destination for each user being added and removed. The property name will be the snake_cased version of the audience name you provide with a true/false value. For example, when a user first completes an order in the last 30 days, we will send an identify call with the property order_completed_last_30days: true, and when this user no longer satisfies we will set that value to false.

When the audience is first created an identify call is sent for every user in the audience. Subsequent syncs will only send updates for those users which were added or removed since the last sync.

Supported Sources and Connection Modes

The first step is to make sure Totango supports the source type and connection mode you’ve chosen to implement. You can learn more about what dictates the connection modes we support here.

Web Mobile Server
📱 Device-mode
☁️ Cloud-mode

To learn more about about Connection Modes and what dictates which we support, see here.


Segment lets you change these destination settings from your Segment dashboard without having to touch any code.

Disable the Totango Heartbeat

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.

Service ID

You can find your Service ID under Settings > Developer Console in Totango.

Track Categorized Pages to Totango

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

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: 12 Jun 2020

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