Skip to main content

Documentation Index

Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt

Use this file to discover all available pages before exploring further.

Use OneSignal to notify users about social activity (likes, follows, invites) and user messages. These alerts can drive re-engagement even when users aren’t currently active in your app.
OneSignal and push notifications are not designed explicitly for real-time communication. They are best used as a fallback when both users are not active on your app.For real-time communication, consider dedicated live chat solutions such as:

​
Social activity notifications

Trigger a push notification when a user is involved in social actions.

​
Common social actions

ActionExample message
Like“Anna liked your post.”
Mention“Leo mentioned you in a comment.”
Tag“Sara tagged you in a photo.”
Invite“Ben invited you to the event.”
Comment“Maya replied: ‘Looks awesome!’”
Follow“James started following you.”
Share“Alex shared ‘Hawaii Album’ with you.”

​
Requirements

​
Setup

​
1. Map users with External ID

Use Aliases & External ID to uniquely identify users in OneSignal.

​
2. Detect the social action

In your backend, track who performed the action and who it affects.
json
{
  "action": "like",
  "actor_id": "user_b",
  "recipient_id": "user_a",
  "post_id": "xyz789"
}

​
3. Send a push notification

Use the OneSignal API to notify the recipient: 
{
  "app_id": "YOUR_APP_ID",
  "contents": { "en": "user_b liked your photo." },
  "include_aliases": { "external_id": ["user_a"] }
}

​
Add-ons

​
Direct (user-to-user) messages

Let users know they have a new message and optionally include message content or a deep link to the chat.
Push notifications are best used as a fallback when both users are not actively chatting in the app.
Send a push when User A sends a message to User B, and B is not currently online or in the chat screen.

​
Setup

​
1. Map users with External ID

Use Aliases & External ID to uniquely identify users in OneSignal.

​
2. Trigger a notification on message send

From your backend, send a push to the recipient using the Create Notification API with the include_aliases field: 
{
  "include_aliases": {
    "external_id": ["USER_B_ID"]
  },
  "contents": { "en": "New message from Anna: 'Hey, you around?'" },
  "headings": { "en": "New Message" },
  "data": {
    "sender_id": "user_a",
    "conversation_id": "chat_1234",
    "click_action": "open_chat"
  }
}

​
Best practices

  • Avoid spamming: Don’t send a notification for every single message. Use batching or only alert after X minutes of inactivity.
  • Respect user settings: Let users mute or disable message notifications if needed.
  • Use routing logic in your app to open the conversation. See Deep Linking for more information.