Skip to main content

Utils

The sdk.utils object on the Server SDK offers a wide array of helper methods to support backend logic in MonoChat Custom Functions. These utilities cover encoding, decoding, role checks, QR code generation, canvas image manipulation, and more.

Categories​

Encoding & Decoding​

  • encode(data, format) – Encodes a string using base64 or other formats.
  • decode(data, format) – Decodes a previously encoded string.
  • serialize(obj) – Serializes a JavaScript object.
  • deserialize(string) – Reconstructs object from serialized string.

Formatting​

  • formatDate(date) – Returns formatted date string.
  • formatDateTime(date) – Returns formatted date-time string.
  • formatDateTimeLocal(date) – Locale-aware date-time string.
  • currency.priceString(isoCode, price, options) – Returns a formatted price string.

Path & Slug​

  • absoluteUrl(path) – Returns full absolute URL.
  • absolutePathString(name) – Resolves relative file/function path.
  • slugify(string) – Converts string to URL-safe slug.

QR Code​

  • generateQrCodeAsync({ data }) – Generates QR code image from data.

Canvas Helpers​

  • canvas.create(width, height) – Creates a canvas object.
  • canvas.loadImage(path) – Loads an image into canvas.

Base64 Upload​

  • uploadBase64Async({ base64, mimeType, fileName }) – Uploads base64-encoded file and returns URL.

Signed File URLs​

  • getSignedFileUrl(url, { expiresIn }) – Returns the URL to read a stored file from. A URL on a private bucket (MonoChat's own storage or omni-message's media) comes back signed for expiresIn minutes (default 60); any other URL comes back unchanged.

Read every stored media or storage URL through it before you fetch it or hand it on, such as a message's fileUrl or an uploaded file's url:

const fileUrl = await sdk.utils.getSignedFileUrl(message.payload.image.fileUrl)
const response = await sdk.lib.fetch(fileUrl)

Timer Helpers​

  • setTimeout(fn, ms) – Delays execution.
  • clearTimeout(id) – Clears timeout.
  • setInterval(fn, ms) – Repeats execution.
  • clearInterval(id) – Clears interval.

Translation​

  • translate('i18n.key') – Translates a given key.

Role Check Utilities​

  • roles.userIsInRoleAsync(roles, { userId, slug }) – Checks if the user holds one of the roles in the tenant itself.
  • roles.userIsInParentRole(roles, { userId, slug }) – Checks the tenant and every tenant above it.
  • roles.userIsInRootRole(roles, { userId, slug }) – Checks the root tenant.
  • roles.addRolesToParentAsync(childRoles, parentRole) – Assigns roles.

roles is a role or permission id, or a list of them; holding any one is enough. The second argument is optional:

  • userId – the user to check. Without it, the user who runs the function. In a function that runs inside a flow (an AI tool, a flow node) that user is the tenant's flow bot, not the customer in the conversation, so pass the customer's or the agent's userId to check them.
  • slug – the tenant to check in. Without it, the function's own tenant. It must be that tenant or one below it: any other tenant throws the error roles-slug-not-allowed. A tenant that does not exist or is archived gives false.
const isAllowed = await sdk.utils.roles.userIsInParentRole(['permissions.tenants.billing.balances.read'], { userId, slug })

The second argument exists only on the server; in a custom view's browser code the role checks always check the signed-in user in the current tenant.

Logging​

Use sdk.utils.logger instead of console.log on the server.

  • logger.info(...args) – Logs info-level messages.
  • logger.warn(...args) – Logs warnings.
  • logger.error(...args) – Logs error messages.
  • logger.debug(...args) – Logs debugging info.

Example: QR Code Logging​

const qr = await sdk.utils.generateQrCodeAsync({ data: 'https://MonoChat.ai' })
sdk.utils.logger.info('Generated QR Code:', qr)