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.

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. Use 0 for in progress and 1 for success. Any other value is shown as failed.

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.

notifyAdmins (true/false) optional

Send the notification to every administrator for this account.

type (String) optional

Set to "error" to show the notification as an error.

from (String) optional

The sender name shown on the notification. Defaults to the name of your app.

data (Object) optional

Details to show when the user clicks the notification. Upsales lists each key with its value in a modal. When you send data, this modal is shown instead of the notification modal described below.

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 without data and the user clicks this notification, 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.object 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 respond with 404 Not Found, we'll show the placeholder "No more information available." instead.