Import tokens

If you are coming from another push provider, Batch provides a way to import your existing iOS or Android tokens from any other push provider.

Here is why you need to import your tokens after a migration:

Token collection: Batch needs to collect all your users' tokens again if you don't import them. Part of your userbase will be unreachable during this period.
App updates: Some users may not update your app. As a consequence, you won't be able to push them after the migration.
Inactive users: In case the OS automatically updates your app, your users will still have to open your app to get a new token.

Batch can import all your existing tokens instantly with basic and custom data (e.g. attributes and arrays). This ensures you won't lose any tokens during the migration and you will still be able to send push messages to 100% of your audience.

Import format

The format of your devices' tokens export must be a valid CSV file (comma or semicolon delimited). Android/iOS devices tokens must be exported separately.

Before sending us your export, please review the format of each field in your import file. The CSV file must contain the following fields, in this order: push_token, install_date ,custom_id, region, language, timezone. Optional columns mean that their value can be empty, but they still must be present.

Id	Description
`push_token`	- Required A device's push token
`custom_id`	- Optional The custom ID of a user if you have one (email address, integer, etc) .
`region`	- Optional Country of the user. If you do not specify a region, the user will automatically be put in the XX (no country) category. This should be written in ISO 3166-1 alpha-2 format. See here for all valid region codes. E.g.`"US"`
`language`	- Required Language of the user in ISO 639-1 format. See here for all valid language codes. E.g.`"en"`
`timezone`	- Optional User's timezone name in TZ database format. If you do not specify a timezone it will be "GMT". See here for all valid timezones. E.g.`"Europe/Paris"`
`custom_data`	- Optional Custom attributes and tag collections. See Importing custom data for more information.

Once you're done, please rename your CSV file as EXPORT_APPNAME_OS_APIKEY.csv (e.g. EXPORT_MYAPP_ANDROID_5BAB93CA7BD1A40183C959DA00CC0F). The "APIKEY" must be the Live API key of the app you will find in the dashboard settings. Then send the csv files to support@batch.com. Our team will notify you once the import is complete.

Importing custom data

Attributes can be attached to imported tokens. All types of attributes supported on profiles can be imported.

They should be represented as a JSON object of tags and attributes and then encoded as Base64.

Attribute rules

Attribute names are strings. They should be made of lowercase letters, numbers or underscores ([a-z0-9_]) and can't be longer than 30 characters (e.g. has_premium).

Their values must be any of the following types:

String
- Must not be longer than 200 characters and can be empty. For better results, you should make them upper/lowercase and trim the whitespaces.
Numbers
Dates
- Must be sent as UNIX timestamps in seconds, and their key wrapped in date(). E.g. "date(birthday)": 1512640800

Array rules

Array names are strings. They should be made of lowercase letters, numbers or underscores ([a-z0-9_]) and can't be longer than 30 characters.

They must be represented as an array of strings. Individual values must be lowercased strings, and not longer than 64 characters.

Example

JSON Representation of profile attributes.

{
  "age": 26,
  "finished_onboarding": true,
  "first_name": "John",
  "date(became_premium)": 1512640800,
  "interests": ["sports", "finance"],
  "items": [
		{
			"brand": "Nike",
			"model": "Air Jordan",
			"price": 165
		},
		{
			"brand": "Adidas",
			"model": "Gazelle",
			"price": 110
		}
	]
}

Which, encoded in Base64 for the CSV ends up being:

ewogICJhZ2UiOiAyNiwKICAiZmluaXNoZWRfb25ib2FyZGluZyI6IHRydWUsCiAgImZpcnN0X25hbWUiOiAiSm9obiIsCiAgImRhdGUoYmVjYW1lX3ByZW1pdW0pIjogMTUxMjY0MDgwMCwKICAiaW50ZXJlc3RzIjogWyJzcG9ydHMiLCAiZmluYW5jZSJdLAogICJpdGVtcyI6IFsKCQl7CgkJCSJicmFuZCI6ICJOaWtlIiwKCQkJIm1vZGVsIjogIkFpciBKb3JkYW4iLAoJCQkicHJpY2UiOiAxNjUKCQl9LAoJCXsKCQkJImJyYW5kIjogIkFkaWRhcyIsCgkJCSJtb2RlbCI6ICJHYXplbGxlIiwKCQkJInByaWNlIjogMTEwCgkJfQoJXQp9

Data lifecycle when importing tokens & their data

Glossary

Anonymous Profile: a Profile without a Custom ID
Identified Profile: a Profile with a Custom ID, shared to Batch after sign-in or login

Trying to import a push token that is already collected by Batch

When your end user starts your app that implements Batch SDK, Batch automatically collects the push token, even if it was previously collected by your former push notification tool.

So, when going through the CSV import file, we first check if the push token doesn't already exist in the Batch Profile base.

In that case, we simply skip the import of the push token and its data.

Import of anonymous push tokens & their data

When processing your import file, Batch creates new profiles for previously unknown push tokens. Here's how it works:

Batch checks if the push token exists in its system.
If not found, a new profile is generated to store the token and its associated data.
When the user launches the app, Batch creates another profile with the new installation's push token, marked as "collected."
The profile with the imported token becomes orphaned.

Import of push tokens & their data when they're linked to a Custom ID

For push tokens associated with Custom IDs, the import process is as follows:

Batch verifies if the push token exists in its system.
If not found, Batch attempts to match the Custom ID from the import file with existing profiles.

Scenario 1: Matching Profile Found

We will merge the imported data with the existing profile according to these rules.

Push token: Added to the existing profile.
Custom attributes:
- If the attribute already exists on the target profile or has been previously deleted (with a null value), the imported attribute will be skipped and the attribute value in the existing profile will be kept.
- If the attribute doesn't exist on the target profile, the imported attribute will be merged into the profile.

No profile exists with this Custom ID

If no profile exists with the Custom ID:

A new identified profile is created.
All data associated with the imported token is linked to this new profile.

Specific behaviors of native attributes

Native attributes (language, region, timezone) can be imported alongside tokens.

Important considerations:

These imported native attributes have the lowest priority for targeting or personalization.
Other methods of setting these attributes (e.g., via API) all take precedence.

Export steps by provider

Importing from Airship

If you're coming from Airship, you will only need to request an export of your devices' tokens to your account manager.

Before sending us the export at support@batch.com, make sure the data is in the format described above and rename the files as follows to make sure our team can import it as quickly as possible: EXPORT_APPNAME_OS_APIKEY.csv. We will notify you once the import is complete.

Importing from PushWoosh

You can request an export of your devices' tokens at help@pushwoosh.com, mentioning your username.

Importing from OneSignal

If you're coming from OneSignal, you will need to request an export of your devices' tokens through an API export. You can find here how to request your raw token export. This can be done from One Signal's dashboard too.

Then, make sure the data is in the format described above and rename the files as follows to make sure our team can import it as quickly as possible: EXPORT_APPNAME_OS_APIKEY.csv

All you have to do now is send us your exports at support@batch.com. Our team will notify you once the import is complete.

What's next

Once your push tokens have been successfully imported to Batch, your whole userbase is reachable and you can migrate your campaigns.

Note that this page is related to token imports for Push v2. Push v1 works in a slightly similar way, but by Platform (iOS, Android).

Documentation > Dashboard > Profiles