Connect a built-in system
A built-in system connects in one step. You give Atender a key, or for Jira you sign in with Atlassian. Atender checks a HubSpot or Stripe key with that system, then creates the connection and publishes its capabilities. A Shopify token is not checked first: a wrong token shows when the first lookup fails. Four systems are built in: Shopify, HubSpot, Stripe and Jira. Shopify, HubSpot and Stripe each serve both the Agent Stack and a tool dock beside the conversation.
Before you start
- A role with the Agent Stacks permission. You need it to connect, change or disconnect a built-in system.
- For HubSpot: a HubSpot service key or a private app access token. To make a service key in HubSpot, go to Development → Keys → Service keys. The key must be able to read contacts, tickets and owners (the scopes crm.objects.contacts.read, crm.objects.tickets.read and crm.objects.owners.read). The owners scope is optional. Without it, the contact owner is not named.
- For Shopify: each store’s domain and an Admin API token from Shopify, and the countries each store sells to.
- For Stripe: a restricted key (rk_) or a secret key (sk_) from each Stripe account, and the countries each account bills. In Stripe, open Developers → API keys and create a restricted key. Give it read access to Account, Customers, Products, Subscriptions, Invoices, Charges and PaymentIntents, and write access to Refunds, Subscriptions and Invoices for the actions you use. A publishable key is refused.
- For Jira: an Atlassian account that can create issues in the agents’ projects, and the Jira Cloud site address, such as acme.atlassian.net. Jira Data Center is not supported.
Steps
- Open Settings → Capabilities.
- Click Connect a system, then choose Built-in.
- Choose HubSpot, Shopify, Stripe or Jira.
- For HubSpot, paste the key into Service key and click Connect HubSpot. Atender checks the key with HubSpot first.
- For Shopify, fill in Store domain, Admin API token and Markets under Connect a store. Add a Catalog tag (optional) to show customers only the products with that tag. Click Connect store. To add more stores, see Several Shopify stores.
- For Stripe, paste the key into Restricted or secret key under Connect your account, choose the account’s Markets, and click Connect Stripe. Atender reads the account from Stripe first. To add more accounts, see Several Stripe accounts.
- For Jira, type your site address in Jira site, for example acme.atlassian.net, and click Connect with Atlassian. Approve the access on the Atlassian page, then return to Capabilities.
- On the Customer identity card, answer Which sign-in field is the customer email?. Choose email, user_id, or Custom… and type the key your sign-in token uses.
- Assign the new capabilities to a specialist, as with any capability. The Agent Stack uses only the capabilities you give it, so you choose which reads and which changes it may make. See Add a capability to a specialist.
What Atender creates
- HubSpot — HubSpot — contact record: name, company, job title, lifecycle stage and owner — Verified customer — reads their data
- HubSpot — HubSpot — tickets: the customer’s tickets with their status, newest first, up to 20 — Verified customer — reads their data
- Shopify — Shopify — order status & tracking — Verified customer — reads their data
- Shopify — Shopify — order history — Verified customer — reads their data
- Shopify — Shopify — product price — Public
- Shopify — Shopify — stock / availability — Public
- Stripe — Stripe — subscriptions: plan, price, status, renewal date and any cancellation — Verified customer — reads their data
- Stripe — Stripe — invoices: the total, the status, what is still due and the link to pay — Verified customer — reads their data
- Stripe — Stripe — payments: the amount, the card, the status, refunds and why a payment failed — Verified customer — reads their data
- Stripe — Stripe — refund a payment: all of it or part of it, to the card that paid — Verified customer — changes their data
- Stripe — Stripe — cancel a subscription: at the end of the paid period or at once — Verified customer — changes their data
- Stripe — Stripe — send an invoice again: Stripe emails an open invoice and its payment link — Verified customer — changes their data
- Jira — Jira — linked issues: the status of issues linked to the verified customer’s own conversations — Verified customer — reads their data
The verified-customer capabilities read only the verified customer’s own data. Atender finds the customer by the email from their verification. The Agent Stack never supplies the email.
The three Stripe changes work the same way. A refund, a cancellation or an invoice email names a payment, a subscription or an invoice the Agent Stack read before. Atender checks that the object belongs to the verified customer before it asks Stripe, and refuses any other one.
Atender acts in Jira as the person who connects it. Issues are created and read with that person’s Atlassian access, so connect with an account that has the access you want the agents to have.
The connection shows Managed by Atender. You cannot change its authentication or its tools in the connection editor.
Several Shopify stores
You can connect one store for each group of countries, for example one store for Norway and one for Sweden. All stores share the same four capabilities.
- Open the Shopify connection in Settings → Capabilities.
- Under Your Shopify stores, click Connect another store.
- Fill in the store and its Markets, then click Connect store.
How the Agent Stack picks a store:
- Each country goes to one store. A customer’s order and product questions go to the store for their country.
- A store with no markets answers the countries that no other store has. Only one store can have no markets.
- If no store serves the customer’s country, the Agent Stack does not look it up.
- If the Agent Stack does not know the customer’s country yet, it asks the customer.
To change a store’s countries, change Markets on the store and click Save changes. When you click Disable on a store, its countries are not answered while it is switched off.
Several Stripe accounts
Stripe accounts work like Shopify stores. You can connect one account for each group of countries, for example one account for Norway and one for Sweden. All accounts share the same six capabilities.
- Open the Stripe connection in Settings → Capabilities.
- Under Your Stripe accounts, click Connect another account.
- Paste the key for that account, choose its Markets, then click Connect Stripe.
How Atender picks an account:
- Each country goes to one account. A customer’s billing questions go to the account for their country.
- An account with no markets answers the countries that no other account has. Only one account can have no markets.
- A Stripe dock reads every connected account and shows what it finds in each of them.
To change an account’s countries, change Markets on the account and click Save changes. An account is connected or not — there is no switch to hold it off for a while.
Verify it worked
- HubSpot: the HubSpot account card shows your account number and the date you connected it.
- Shopify: your stores show under Your Shopify stores.
- Stripe: your accounts show under Your Stripe accounts. An account on a test key carries a Test mode badge.
- Jira: the Jira site card shows your site address.
- The new capabilities show as Published in the Capabilities list.
Disconnect a system
- HubSpot: click the trash icon on the HubSpot account card, then click Disconnect.
- Shopify: click the trash icon on a store, then click Disconnect. The other stores keep answering their countries.
- Stripe: click the trash icon on an account, then click Disconnect. The other accounts keep answering their countries.
- Jira: click the trash icon on the Jira site card, then click Disconnect.
When you disconnect HubSpot, the last Shopify store, the last Stripe account or Jira, Atender removes the connection and its capabilities. Nothing changes in HubSpot, Shopify, Stripe or Jira.
Troubleshooting
-
Symptom: “HubSpot refused this key.” Fix: The key is wrong, or it cannot read contacts and tickets. Atender saved nothing. Make a new key with the scopes above and try again.
-
Symptom: “Norway already goes to your-store.myshopify.com. Each country goes to one store.” Fix: Another store already serves that country. Remove the country from one of the two stores. Atender saved nothing.
-
Symptom: “your-store.myshopify.com already answers the countries no other store has. Give this store its countries.” Fix: Only one store can have no markets. Choose the countries for the new store.
-
Symptom: “This store was set up by Atender by hand. Contact support to add a second store.” Fix: Your first store was connected by the Atender team before this setup existed. Contact support to add another store.
-
Symptom: “HubSpot is already connected.” Fix: A workspace has one HubSpot account. Disconnect it first to connect another.
-
Symptom: “Paste a secret key (sk_…) or a restricted key (rk_…).” Fix: The key is a publishable key or another kind of value. Copy the restricted or secret key from Developers → API keys in Stripe. Atender saved nothing.
-
Symptom: “Stripe refused this key.” Fix: The key is wrong, or Stripe has withdrawn it. Make a new key and try again. Atender saved nothing.
-
Symptom: “This key may not read the Stripe account. Give the restricted key read access to Account.” Fix: Atender reads the account first to learn its name and its mode. Add Account read to the restricted key in Stripe, then try again.
-
Symptom: “This Stripe account is already connected.” Fix: One Stripe account connects once. To change its countries, open the account and change Markets.
-
Symptom: “Norway already goes to Acme AS. Each country goes to one Stripe account.” Fix: Another account already bills that country. Remove the country from one of the two accounts. Atender saved nothing.
-
Symptom: The Agent Stack cannot find the customer’s contact, tickets or orders. Fix: Check the Customer identity card. The sign-in field you chose must hold the customer’s email. A customer who verified with a one-time code has an email only when the field is email or user_id.
-
Symptom: The Jira site card shows a Connect again prompt. Fix: Atlassian no longer accepts the sign-in. Click Connect again and approve the access on the Atlassian page. Sign in with an account that can still create issues in the agents’ projects.