How To Integrate Nango

The steps to integrate Nango.
0. Configure your integrations in Nango
This one time setup tells Nango how your integration should work:
- Enable the API (e.g. Zendesk) once in Nango. Enter scopes and authorization details.
- 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.
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.
{
"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.
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.
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.