• iOS
  • Android
  • Windows
  • Cordova
  • Web
  • Unity
  • Adobe Air
  • Dashboard
  • API
  • Guides
  • FAQ
  • Documentation > Guides

    Migrating to Batch

    If you are coming from another push provider, Batch provides a way to import your existing tokens from Parse, Urban Airship or 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. This ensures you won't lose any tokens during the migration and you will still be able to push inactive users or outdated users.


    Here are the three steps you need to follow before exporting your tokens:

    1. Upgrade your plan: The token import feature is only available for Pro users and higher.
    2. Update your app: Make sure Batch is already integrated in your app. This ensures no users are omitted between the moment you export your tokens and the moment Batch starts collecting your new users' tokens.
    3. Send us your export: You can send us your export at support@batch.com.

    Now let's see how to generate your tokens export from your old push provider.

    Importing your tokens

    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. On iOS, please make sure the push tokens of the production and the development’s P12 certificate are not in the same export.

    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.

    Parameters Description
    push_token Required - A device's push token.
    install_date Optional - Install date of the app on the user’s device. The date should be written in ISO 8601 format: YYYY-MM-DDTHH:MM.
    E.g. 2007-04-30T14:30
    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 Required - User's timezone in TZ format. If you do not specify a timezone, the timezone of the user will be automatically "GMT". See here for all valid timezones.
    E.g. Europe/Paris

    Once you're done, please rename your CSV file as EXPORT_APPNAME_OS_APIKEY.csv and send it to support@batch.com. Our team will notify you once the import is complete.

    Importing from Accengage

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

    Before sending us your export at support@batch.com, please make sure you have renamed it as follows: EXPORT_APPNAME_OS_APIKEY.csv.

    Importing from Parse

    First, go to your dashboard, select your app and click on "App settings". Then click on General in the side menu and the "Export app data" button.

    Parse Export

    If everything goes well, you will receive an email containing a .zip file with all your push tokens in a JSON file. Please rename the zip file as follows to make sure our team can import it as quickly as possible: EXPORT_APPNAME_OS_APIKEY.zip.

    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.

    As Parse describes it in its documentation (see the paragraph starting with "By default"), Parse used its own GCM sender ID instead of the one generated by Google.

    Unless you specified your own GCM sender ID in your code when you integrated Parse, none of the Android tokens collected by Parse are pushable by another push provider.

    Importing from PushWoosh

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

    Before sending us your export at support@batch.com, please make sure you have renamed it as follows: EXPORT_APPNAME_OS_APIKEY.csv. We will notify you once the import is complete.

    Importing from Urban Airship

    All you need to do is to select your app, go to SettingsAPI & Integrations and note your App Key and your App Master Secret.

    Urban Airship APIs

    Then, just send them to us at support@batch.com with your app name and your Batch API key and we will take care of exporting and importing your tokens for you.

    Targeting imported users

    After we’ve completed your tokens import, a new IMPORTED segment will be available. Imported users

    There are a few things you need to keep in mind before targeting your newly imported users:

    • The IMPORTED segment is not targeted by default when you create a new campaign. Don't forget to select it the next time you want to send a notification.
    • Imported users will be progressively analysed and transferred to other Smart Segments after their first session.
    • The first time you send a notification to your imported users, Batch will clean the inactive or invalid tokens that may come from your previous push provider. Depending on how many invalid tokens we find, the number of users in the IMPORTED segment will decrease a few days after the import.