The steps to integrate Nango.

0. Configure your integrations in Nango

This one time setup tells Nango how your integration should work:

  1. Enable the API (e.g. Zendesk) once in Nango. Enter scopes and authorization details.
  2. Enable the use cases you need for the API: E.g. sync issues and repos, send message, create contact, etc.
    • You can enable pre-built use cases from Nango in the dashboard
    • Or you can deploy your own, custom use cases into your Nango account

You can change the enabled use cases for the API at any time later on.

1. Get user permission in your app

Integrate the Nango frontend SDK into your application, to get the user’s permission to access their data.

When the user clicks the button in your app to connect the integration, a popup will guide them through the (O)Auth flow.

Store connectionId & integrationId in your database. You’ll need these to get the user’s data later.

Frontend: Trigger the OAuth flow.
const integrationId = 'zendesk';
const connectionId = 'user123';

// Shows authorization popup to the user
const result = await nango.auth(integrationId, connectionId); 

if (result.ok) {
    // Auth flow succeeded, integration has been set up
    saveToDatabase(connectionId, integrationId);
}

When a new user connects your integration, Nango automatically starts fetching their data (e.g. issues, contacts, files, etc.) in the background.

2. Get data update notifications

Nango will alert your app with a webhook whenever there is new data available.

You choose how often to check for data updates. Nango will only alert you when there are actual changes.

Key fields in the webhook payload, essential for later data retrieval:

  • connectionId : The specific end-user related to the data.
  • model : The data model for which new data is available.
  • queryTimeStamp: Timestamp to locate recent modifications.
Backend: Receive this webhook payload.
{
    "connectionId": "user123",
    "model": "ticket",
    "providerConfigKey": "zendesk",
    "responseResults": { "ticket": { "added": 2, "updated": 6, "deleted": 0 } },
    "queryTimeStamp": "2023-05-31T11:46:13.390Z"
}

3. Collect and save the new data

When you receive the webhook, fetch the most recent data from Nango using the backend SDK or API.

Nango returns the fetched data in your own, custom data model. It can even be standardized across different APIs.

You can directly save this data to your database, or process it further, as needed.

Backend: Fetch & save new records.
const records = await nango.listRecords<Ticket>({
    providerConfigKey: 'zendesk',
    connectionId: 'user123',
    model: 'ticket',
    delta: queryTimeStamp
});

saveToDatabase(records);

4. Write back to external APIs

Push updates back to external APIs in a way that is:

  • Synchronous: Have your changes immediately reflected.
  • Unified: Benefit from standardized schemas across different APIs.
  • Customizable: Support intricate workflows and combined API calls.
Backend: Write back to external APIs.
const result = await nango.triggerAction({
    providerConfigKey: 'zendesk',
    connectionId: 'user123',
    action: 'create-ticket',
    input: { "title": "...", "content": "..." }
});

Next Steps

Dive deeper with the following guides:

Questions, problems, feedback?

We’re here to help! Please reach out on the Slack community, we are very active there. We’re here to help! Please reach out on the Slack community, we are very active there.