Notifications

Send notifications

Sends additional notifications to a user for unanswered messages in a specific conversation.

If a user has notifications enabled, TalkJS already automatically sends that user notifications as soon as the conditions for notifying a user are met. You can use this endpoint to send additional notifications for any unanswered messages in a conversation.

An unanswered message is any message that another user sends to a conversation, after the user's own latest message.

For example, in the following conversation between a buyer and a seller, the seller hasn't answered the buyer's final message:

Buyer: Hey, I'd like to order this chair
Seller: Sure, it's still available!
[Seller goes offline]
Buyer: Could you tell me how wide it is?

When you trigger a notification, all participants in a conversation, apart from the one who sent the latest message, get notified if they have notifications enabled.

If a user has multiple unanswered messages, they receive only one notification that bundles information about all the unanswered messages.

Notification types

You can send an email notification, an SMS notification, or notifications of both types at the same time.

Webhooks

To receive information about the status of the notifications, you can use webhooks to listen for notification.triggered and notification.sent events.

Use notifications carefully

Beware of sending notifications too frequently, as your users may get overloaded.

Sending notifications doesn't distinguish between the situation where a conversation has ended (for example, when the last message is "Ok, bye!") and one that still needs an answer (for example, when the last message is "Can you help?").

If you only want to send additional notifications when certain conditions are met, you can implement your own filter before programmatically triggering notifications.

post/v1/{appId}/conversations/{conversationId}/notifications

Request

Base URL
https://api.talkjs.com
Auth
- HTTP bearer
- or HTTP bearer
TypeScript
https://skmtc.dev/talkjs/apis/talkjs-api/docs/v1/:appId/conversations/:conversationId/notifications/post.ts
A function with typed inputs. Its response is checked against the schema.

Path parameters

appIdstring required

Example:abcd1234

A unique identifier of your TalkJS app. You can find your app ID on the Settings page of your dashboard.

conversationIdstring required

Example:0123456789abcdef

A unique identifier of a conversation.

Request body

channelsstring[]

The channels in which to trigger notifications. Provide at least one channel in which to trigger notifications.

recipientsstring[]

An array with user ID of the participants who should receive the notifications. Omit this field to trigger notifications for all participants who have unanswered messages.

Example request

{
  "channels": [
    "email",
    "sms"
  ],
  "recipients": [
    "alice",
    "zayneb"
  ],
  "smsSettings": {
    "smsTemplate": "({{app.name}}) {{sender.name}}: \"{{messages}}\". Reply here: https://yoursite.com/inbox"
  },
  "emailSettings": {
    "footer": "On behalf of {{sender.name}},\nThe {{app.name}} team",
    "header": "Hi {{recipient.name}},\n\n{{sender.name}} wants to chat with you on {{app.name}}:",
    "subject": "{{sender.name}} wants to chat with you on {{app.name}}",
    "inboxUrl": "https://yoursite.com/inbox",
    "senderName": "{{sender.name}} (via {{app.name}})",
    "inboxLinkText": "Click here to join the chat.",
    "replySeparator": "--- Write ABOVE THIS LINE to post a reply via email ---",
    "unsubscribeText": "Unsubscribe from all chat emails"
  }
}

Response

Empty response

object required