Activating integrations
Where to switch on the outside services your app uses (payments, maps, SMS, WhatsApp, notifications), what each state of the card means, and which guide to follow for each provider.
The app can have the checkout screen, the address field or the send-message button ready and still not work: the one that carries out those actions is the provider, with your account. Without the saved credential, the screen exists and the action does not happen.
Where it lives
The Integrations tab, in the editor. It has two sub-tabs:
- Providers: one card per service in the catalog, with search by name, the filters All, Connected and Not connected, and the categories (Payments, Location, Notifications, Productivity and others);
- External APIs: to register an API that is not in the catalog, with the key kept on the server and used by a backend function.
Two similar topics live in other tabs: social login (Google, Apple, Microsoft and others) is in Authentication, and the email sending domain is in Domains.
Plan
The Integrations tab opens on any plan, and some of the cards work on all of them, Free included. The others require the Builder plan.
| Works on any plan | Requires the Builder plan |
|---|---|
| Google Maps | Stripe, Mercado Pago, Pagar.me and Hotmart |
| SMS (Twilio) | WhatsApp and Telegram |
| Slack and Discord | Shopify, Meta (Facebook/Instagram) and Google Workspace |
| Meta Pixel, Google Analytics, Google Tag Manager, Microsoft Clarity and Hotjar | Notion, Airtable and Mailchimp |
| Baseportal Chat, Crisp and Tawk.to | Webhook (outgoing) |
| Cookie consent | Google AdSense |
On the Free and Starter plans, the cards that require Builder appear faded, the notice "Integrations are a Builder plan feature" sits at the top of the tab, and clicking one of those cards takes you to the plans. The rest open and connect normally.
The External APIs sub-tab is also a Builder plan feature.
The server also checks the plan on every use for WhatsApp, Telegram, Shopify, Meta, Notion, Airtable, Mailchimp and Webhook (outgoing). If the account leaves Builder, those integrations stop responding in the published app, even with the credential still saved.
Email with your own domain is a separate case: it lives in the Domains tab and is available on any paid plan. See Email with your own domain.
How to connect a card
- click the card;
- fill in the fields it asks for (each guide below says where to get each one);
- click Save and activate.
The platform saves and, with providers that allow it, tests the credential right away. A secret field that is already saved then shows "· configured" next to its name. Disconnect, at the bottom of the card, deletes the credential from the platform.
To change one key on a card that is already connected, type only that field and save. A field left blank keeps its saved value, and what the platform stores by itself (such as the Stripe webhook signing secret and the authorized access of the authorization-based connections) stays in place.
The keys are stored encrypted on the server and never come back to the screen or reach the browser of the people using the app.
What each state means
| State on the card | What it means |
|---|---|
| Not connected | nothing was saved on this card |
| Connected | the credential is saved and, when the provider allows testing, it passed the test |
| Configuration error | the credential is saved, but the test refused it (wrong key, expired, missing permission, invalid format) |
Not every card can test the credential on save, and that changes what Connected guarantees:
- really test it, by talking to the provider: Stripe, Mercado Pago, Pagar.me, Hotmart and Google Maps;
- check only the format of the ID: Meta Pixel, Google Analytics, Google AdSense, Google Tag Manager, Microsoft Clarity, Hotjar and the chats (Baseportal Chat, Crisp, Tawk.to);
- only save, with no test: SMS (Twilio), WhatsApp, Slack, Discord, Telegram, Notion, Airtable, Mailchimp, Webhook (outgoing), Shopify, Meta (Facebook/Instagram) and Google Workspace. On these, Connected means "saved", and the proof that it works is the first real send.
When the test fails, the window shows "Saved, but validation failed" followed by the reason the provider gave. The way out is to fix the credential at the provider, not to paste the same value again.
Test and production keys
Several providers give two sets of credentials: a test one, which moves no money and delivers nothing for real, and a production one.
- Stripe, Mercado Pago and Pagar.me have no environment switch on the card: what decides is which key you paste. Test key, test charge. Swap in the production keys before selling;
- Hotmart has the option "Use the test environment (sandbox)". Leave it unchecked with production credentials;
- WhatsApp and Twilio have limits in test mode (allowed destination numbers, a token that expires). Each one's guide explains.
Integration credits
Setting up an integration costs no credits at all. What costs are integration credits, the currency for running the app, when the published app uses the provider: every SMS (including the SMS login code), every automation email or notification sent by the app, every notice on Slack or Discord, every WhatsApp or Telegram message and every call to Shopify, Meta, Notion, Airtable, Mailchimp, Webhook (outgoing), Google Workspace and External APIs.
The charge only happens when the provider accepts. A call that fails is not charged. With the balance at zero, those sends are refused until the balance comes back.
Payments and Google Maps do not consume integration credits. Maps uses the quota and billing of your Google project.
The balance and the month's usage are in the panel, under Billing. See Credits.
The assistant tells you what is missing
After a build, the chat shows the To make it really work card, with each integration the app's code uses that is not active yet. Each item has two buttons:
- Activate in Integrations: opens the Integrations tab straight on that integration's card (for payments, in the Payments category, where you choose the gateway);
- How to activate: opens that provider's guide, in this documentation.
When an integration becomes active, the assistant confirms it in the chat.
The assistant also reads, in every conversation, the state of your integrations: which are connected, which are saved but have a problem and which were never connected. You can ask in the chat "is Stripe active?". It sees the state, never the value of the keys.
Guides by provider
| Integration | Guide |
|---|---|
| Stripe, Mercado Pago, Pagar.me, Hotmart | Payments |
| Google Maps | Google Maps |
| Email with your domain | Email with your own domain |
| SMS (Twilio) | SMS with Twilio |
| Shopify, Meta (Facebook/Instagram), Google Workspace | Connections by authorization |
| Notion, Airtable, Mailchimp | Notion, Airtable and Mailchimp |
| Webhook (outgoing), Slack, Discord, Telegram | Webhooks and notifications |
| Code on the server and APIs blocked in the browser | Backend functions |
The Analytics cards (Meta Pixel, Google Analytics, Google Tag Manager, Microsoft Clarity, Hotjar), the Chat cards and the Cookie consent card ask only for an ID, and the card's own description says where to find it.
Common problems
- The card is green and nothing happens. Check which group it is in on the list above: on the cards that only save, Connected does not prove the key is right. Do a real send and read the error;
- I saved one gateway and the other disappeared. Stripe, Mercado Pago and Pagar.me share the same slot: only one is active per app, and saving another replaces the previous one. The old gateway's keys do not carry over to the new one: fill in the new gateway's fields;
- The card opens the plans screen. The account is on Free or Starter and that card requires Builder. See the table in the Plan section above.