Integrate Nango - Overview

High-level steps to ship an integration with Nango.

The steps to integrate Nango.

1. Get user permission in your app

Use the Nango frontend SDK to get the user’s permission to access their external data.

Nango guides the user through the (O)Auth flow in a popup window.

Store the connectionId & integrationId in your database to retrieve 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) {
    // The auth flow succeeded. The integration is 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. Receive data update notifications

Nango uses webhooks to notify your backend when external user data has been added, updated or deleted. Nango will only alert you when there are actual changes.

Backend: Webhook payload with new data

{
    "connectionId": "user123",
    "model": "ticket",
    "providerConfigKey": "zendesk",
    "responseResults": { "ticket": { "added": 2, "updated": 6, "deleted": 0 } },
    "modifiedAfter": "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 data in the schema of your choice, which can 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',
    modifiedAfter: modifiedAfter
});

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 composed API calls.

Backend: Write back to external APIs.

const result = await nango.triggerAction({
    providerConfigKey: 'zendesk',
    connectionId: 'user123',
    action: 'create-ticket',
    input: { "title": "...", "content": "..." }
});

Questions, problems, feedback? Please reach out in the Slack community.