App callback – Upsales Help Centre

App callback is a way for your app to save data, update log and notify users from any Upsales request you receive.

Requests with app callback

You'll know app callback is available if the request body has a callbackUrl property.

Almost all requests, except for status requests, supports app callback.

Sending app callback

There's two ways to send app callback: respond to the request or post to callbackUrl later.
Responding to the request

Respond with 200 OK and an app callback object as callback property in the json body. e.g.,

{
 "callback": {"notify": "Hello!"},
 "maybeSomeOtherStuff": true
}

But hurry up! You got 30 seconds before the request times out ⏱

Posting to callbackUrl later

Need to crunch some numbers, sync lots and lots of companies or anything else that takes 30 seconds or more?

Post an app callback object to callbackUrl whenever you're ready 😴

curl -H "Content-Type: application/json" -X POST -d '{"notify": "Hello!"}' "<callbackUrl>"

Please note 1: a callbackUrl is only available once, and only as long as you didn't respond with a callback property to the request.

Please note 2: your app callback object has to be less than 100kb or you'll get an error.

App callback object

The app callback object has the following properties.

status(number) optional

Set a status for the requests log entry. Defaults to 1 simply by using app callback

message (String) optional

Set a message to the request log entry.

appData (Object) optional

Save some app data for this customer. This will be sent in future app requests body.

userAppData (Object) optional

Same as appData but scoped to the user. Will be sent in future app requests. Only available if your app is set to userConfigurable.

notify (String) optional

Send an in-app notification. Recipient is the user who initiated the app run, can be overridden with notifyUserIds or notifyAll.

Good to know

When the user clicks the notification, you can display a widget with more information - scroll down to the "notification modal" part to learn more.

notifyUserIds (Array) optional

Specify the Upsales ids of the users you want to receive the notification.

notifyAll (true/false) optional

Send the notification to every user for this account.

Example object

{
 "appData": {"externalId": "abc123"},
 "userAppData": {"externalId": "user1"},
 "status": 1,
 "message": "A message for the log",
 "notify": "Hello from my app"
}

Notification modal

If your app callback sent a notification and the user clicks this notification, within 90 days*, we'll do a request to the /widget/notification endpoint of your app and you can display additional information to the user.

https://yourapp.com/widget/notification

The data property in the request body will contain the log entry for the request you sent the notification from.

Respond with a widget object, e.g.,

{
 "type": "widget",
 "rows": [
 {
 "type": "markdown",
 "markdown": "**Hello!**"
 }
 ]
}

If you don't respond to this request, we'll simply show a placeholder "No more information for this notification" instead.

* Log entries that's been updated from an app callback are available for 90 days after the request was initiated. If a user clicks the notification modal after those days the placeholder text will be shown instead.