Chat in your iOS and Android app: the mobile SDK
On this page
The Deskwoot mobile SDK puts your live chat into your own iOS and Android app as a native screen, not as a web page. Your customers write to your team and your AI bot right in the app, and your team answers in Deskwoot as usual. When the app is closed, replies reach the customer's phone as push notifications. Your developer builds the SDK into the app with the help of the developer docs. You do 2 things in Deskwoot, both in your live chat inbox under Chat in your iOS and Android app: you copy the widget token for your developer, and you save your Apple key and your Firebase service account so Deskwoot can send the push notifications.
What your customers get in your app
It is the same chat as on your website. The app reads the same inbox settings (your brand color, your texts, your team, your AI bot and your help center) and shows the look you picked for the inbox: Plain, Welcome or Direct. Conversations from the app land in that inbox, and your team answers them like any other chat.
- The chat is a native screen of your app on iPhone, iPad and Android, not a web page. Only the text of a help article shows in a web view.
- Customers write to your team and your AI bot, search your help center and read the replies without leaving the app. They can send photos and files, and photos taken with the camera when your app allows the camera.
- The chat speaks the 10 visitor languages of your website chat. It uses the inbox's fixed language if you set one, otherwise the language of your app, otherwise English. By default it is light or dark like your app.
- When a reply arrives while the app is open but the chat is closed, a small card slides up at the bottom of the app with the writer's picture, their name and 2 lines of the reply. A tap opens the conversation. Your developer can turn the card off.
- The app knows how many replies the customer has not read yet, for example for a badge on your help button. It can also show the round chat button of your website over the app, but that button stays hidden unless your developer turns it on.
- When the app is closed, replies arrive as push notifications, once you set them up (step 2 below).
Your app decides where the chat opens: at its start page, at the customer's newest conversation, at a new conversation with a text of your choice already typed in (the customer can change it and sends it themselves), or right at your help center. Most apps open it from their own help button.
What you need
- A live chat inbox in Deskwoot. The app uses its widget token. With the token of the inbox on your website, chats from the app and from the website land in the same inbox. To keep them apart, create a second live chat inbox for the app.
- Your own app for iPhone and iPad (iOS 15 or later), for Android (Android 5.0 or later), or both. The SDK is native: Swift on iOS, Kotlin or Java on Android. Android apps built with Views and with Jetpack Compose both work. There is no package for React Native or Flutter (see the questions below).
- A developer who builds the SDK into your app. Everything they need is in the developer docs.
- For push notifications on iPhone: an Apple developer account in which you may create keys. Apple allows that to the Account Holder and to Admins.
- For push notifications on Android: access to the Firebase project of your Android app. The app needs Firebase Cloud Messaging.
- In Deskwoot, the right to manage inboxes. Administrators have it, and so do agents whose custom role includes Manage inboxes.
You can use it on any Deskwoot plan. Deskwoot checks no plan for the SDK or for push notifications, and every plan includes live chat inboxes.
Step 1: Give your developer the widget token
- Go to Settings > Inboxes and open the live chat inbox the app should use.
- Under Setup and privacy, click Chat in your iOS and Android app.
- At the top, under Widget token, click Copy and send the token to your developer. The app hands it to Deskwoot in one call,
Deskwoot.setup, when it starts. - At the bottom of the panel, How to add the SDK to your app opens the developer docs. Send your developer that link as well: deskwoot.com/docs/mobile.
That is all the chat itself needs: it works in the app without push notifications too. Push notifications (step 2) add the replies that arrive while the app is closed.
Step 2: Set up push notifications
Push notifications take work on both sides. Your developer prepares the app as the developer docs describe under Push notifications. You save the credentials Deskwoot sends with: an APNs auth key from Apple for iPhones, and a service account from Firebase for Android phones. Deskwoot's server then sends every push with your own Apple and Google accounts. The SDK in the app never talks to Apple or Google itself.
You can set up iOS, Android or both. Each block in the panel has its own Save button. When you click it, Deskwoot first asks Apple or Google whether they accept what you entered, and saves it only if they do. If they refuse, a line under the block says what is wrong, and nothing is saved. If Apple or Google do not answer, try again in a moment.
Push notifications on iPhone: your APNs auth key
You need 4 things from your Apple developer account:
- The APNs auth key, a file that ends in
.p8. In your Apple developer account, go to Certificates, Identifiers & Profiles, click Keys and create a key with the Apple Push Notification service turned on. Download the file and keep it safe: Apple lets you download it only once. - The key ID. Apple shows it below the key's name when you select the key under Keys. It has 10 letters and digits.
- Your team ID. It is in your Apple developer account under Membership details, also 10 letters and digits.
- Your app's bundle ID, such as
com.example.app. Your developer knows it from Xcode, and Apple lists it under Certificates, Identifiers & Profiles, Identifiers.
Apple can limit a key to one environment, sandbox or production. Apps from the App Store and from TestFlight use production, development builds use sandbox. When you save the key, Deskwoot asks Apple which environments it works for, and if it is only one, a line in the iOS block tells you. For a key limited to the sandbox the line is a warning: iPhones with your app from the App Store or TestFlight get no push notifications, so create a key for production as well and save it. For a key limited to production it is just a note: development builds of your app get no push notifications. Either way the block says Connected, because Apple accepted the key. So make sure your key works for production, where your customers' app runs.
Then, in Deskwoot:
- In Chat in your iOS and Android app, go to the iOS block.
- Paste the content of the
.p8file into APNs auth key (.p8), or click Upload .p8 file and choose the file. - Enter the Key ID, the Team ID and the Bundle ID.
- Click Save.
Apple checks the key, the key ID and the team ID together, so all 3 must come from the same key, and the bundle ID must belong to your team. Once Apple accepts them, the block says Connected and shows the key ID, team ID and bundle ID. Only iPhones with the app of that bundle ID get push notifications.
Push notifications on Android: your Firebase service account
Push notifications to Android phones go through Firebase Cloud Messaging, with a service account of the Firebase project your Android app uses.
- In Firebase, open your app's project, then Project settings, then Service accounts, and generate a new private key. Firebase gives you a JSON file.
- In Deskwoot, in Chat in your iOS and Android app, go to the Android block.
- Paste the content of the file into Service account JSON, or click Upload .json file and choose the file.
- Click Save.
Google checks whether this service account may send messages in its project. For that, its key must be valid, it needs a role that may send messages, and the Firebase Cloud Messaging API must be turned on in the project. Once Google accepts it, the block says Connected and shows the project and the service account's email address. Whether the Android phones really belong to this project only shows with the first real push (see the next section).
What the status says
In the overview of the inbox, the row Chat in your iOS and Android app shows one of these:
- Not set up: no push credentials are saved. The chat in your app still works, just without push notifications.
- Push notifications on iOS, Push notifications on Android or Push notifications on iOS and Android: the platforms whose credentials are saved.
- Not sending: Apple or Google refused the pushes Deskwoot tried to send with your saved credentials.
In the panel, each block shows its own status: Connected, Not set up or Not sending. With Not sending, a line in the block says why:
- Apple refuses the key, the key ID or the team ID. Save the right ones.
- Apple refuses the bundle ID. Save the bundle ID of your app.
- Google refuses to send with this service account. Check that its key still exists, that it has a role that may send messages, and that the Firebase Cloud Messaging API is turned on in its project.
- The Android phones belong to another Firebase project than the service account. Upload the service account of your app's Firebase project.
Not sending stays until a push goes through again or you save new credentials. The iOS block can also say that some iPhones use another bundle ID than the saved one, and how many. Those iPhones get no push notifications, so check that the saved bundle ID is the one of your app.
Saved keys: replace or remove them
After you save, the field for the key or the JSON is empty again, with a note that one is saved. Deskwoot stores the key and the JSON encrypted and never shows them again, neither on this page nor through the API. What stays visible is the key ID, the team ID and the bundle ID, and for Android the Firebase project and the service account's email address.
- To replace the key or the service account, paste or upload the new one and click Save. Deskwoot checks it with Apple or Google again.
- To change only the key ID, the team ID or the bundle ID, edit the field and click Save. The saved key stays, so you do not need to upload it again.
- To remove a block, click Remove and confirm with Remove. From then on, iPhones (or Android phones) get no push notifications until you add new credentials. The chat in your app keeps working.
When a push notification goes out
Deskwoot sends a push for each reply the customer sees in the chat: a reply from a team member, an answer from your AI bot or an automatic message. It never sends one for the customer's own messages, for private notes or while the AI bot is still typing its answer. Conversations marked as spam and blocked contacts get none.
- If the customer was not online a moment before, the push goes out right away.
- If they were online a moment before, Deskwoot waits 12 seconds. If they have read the reply by then, no push goes out. A customer who is looking at the conversation is not disturbed.
- Each reply rings the phone once. It goes to every phone on which the customer uses your app with this inbox, up to 10 phones.
- If the phone is off or offline, Apple and Google keep the push for a day and then drop it.
The title of the notification says who wrote: the team member's first name or the name of your AI bot, otherwise the name of your business. The text shows the reply as plain text, up to 160 characters. For a reply that holds only a file, it says "Sent a file" in the language of the phone. A tap on the notification opens the conversation in your app.
Logged in customers in your app
Without more setup, a customer chats in the app as an anonymous visitor, and the conversation stays on that phone. If customers log in to your app, the app can tell the chat who they are. Their conversations then follow them to every device and to your website chat on the same inbox, and your team sees who is writing.
This works exactly like identity verification on your website, with the same secret key, which you create in the same live chat inbox under Recognize logged in customers. Your server signs the customer's user id with that key, and after your own login, the app hands the user and the signature to the SDK. How to create the key and sign the user id is in Identity verification for logged in customers. The call in the app is in the developer docs.
The key belongs on your server only. Never build it into the app: anyone who unpacks the app could read it and chat as any of your customers.
When a customer logs out of your app, the app tells the SDK. The SDK then deletes what it kept about that customer on the phone, the phone stops getting push notifications for them, and the next chat starts as a new anonymous visitor. Their conversations stay in Deskwoot and come back when they log in again.
Frequently asked questions
Does it cost extra, and which plan do I need?
The SDK and push notifications have no price of their own, and Deskwoot checks no plan for them. Every plan includes live chat inboxes, so any plan works. For push notifications you use your own Apple developer account and your own Firebase project.
Is there an SDK for React Native or Flutter?
No. Deskwoot has native SDKs for iOS (Swift) and for Android (Kotlin and Java), and no package for React Native or Flutter. In an app built with them, you can show your website chat in a web view with the embedded mode of the widget. Embedded mode: the chat in a container or full screen shows how.
Do I need Firebase on iOS?
No. Deskwoot sends push notifications for iPhones straight to Apple with your APNs auth key, and the SDK brings no Firebase. You need Firebase only for Android.
Who sends the push notifications, Deskwoot or us?
Deskwoot's server sends them, with your APNs auth key and your Firebase service account, so they go out through your own Apple and Google accounts. Your app only hands its push token to the SDK when it starts. Your own push notifications stay yours: the SDK takes only the ones from Deskwoot and leaves all others to your app.
Does the SDK ask my customers for permissions?
It never asks for permission to show notifications. Your app asks for it when it suits, as it does for its own notifications. On Android 13 and later, no notification shows without it. Besides that, the SDK needs no permission on iPhone and only internet access on Android. Customers can send photos and files without any permission. The camera works only when your app allows it. The card that shows a reply while the app is open needs no permission either.
What does the customer see when the app is closed?
A push notification with the name of who wrote and up to 160 characters of the reply. A tap opens the conversation in your app. If the app is open and the chat is closed, a small card at the bottom of the app shows the reply instead. While the customer looks at that conversation, no notification shows.
Was this guide helpful?
Keep reading
- Customizing your chat widgetMatch the Deskwoot chat widget to your brand: color, theme, language, welcome texts, avatar, suggested articles and more, all in your live chat inbox settings.Read guide
- Embedding the WidgetAdding the Deskwoot chat widget to your website takes just one short snippet of code. The widget loads asynchronously and does not affect your page load performance.Read guide
- Open the chat widget from your own buttonHide the chat bubble and open the live chat from your own button or link with window.deskwootWidget.open().Read guide
Ask Fynn about this guide
Get a short answer from this guide and the rest of the help center.