Callbacks and events

Chat supports HTTP callbacks (webhooks). You can listen for event callbacks and add app logics accordingly. Once a registered callback is triggered by a specified type of event, the Chat server sends an HTTP POST request to your app server, notifying you that the event occurs. The request body is a JSON string encoded in UTF-8 characters.

This page introduces the events and callbacks in Chat.

When a user logs in to or logs out of the Chat app, the Chat server sends a callback to your app server.

Log in to the app

When a user logs in to the Chat app, the Chat server sends a callback to your app server. The sample code is as follows:

{
    "callId":"XXXX#XXXXe393c568-5ae5-4a0e-8a2c-008b52b49eed",
    "reason":"login",
    "security":"XXXXae2eXXXXced298883a0cf06d41b9",
    "os":"ios",
    "ip":"************",
    "host":"*******",
    "appkey":"XXXX#XXXX",
    "user":"XXXX#XXXXtstXXXX/ios_XXXX01fd-b5a4-84d5-ebeb-bf10XXXX0442",
    "version":"3.8.9.1",
    "timestamp":1642585154644,
    "status":"online"
}

Field	Data Type	Description
`callId`	String	The ID of the callback. The unique identifier assigned to each callback, in the format of `{appKey}_{uuid}`, where the value of `uuid` is randomly generated.
`reason`	String	The reason that triggers the callback. `login` indicates that a user logs in to the app.
`security`	String	The signature in the callback request used to confirm whether this callback is sent from the Chat server. The signature is the MD5 hash of the `{callId} + {secret} + {timestamp}` string, where the value of `secret` can be found on Agora Console.
`os`	String	The operating system of the device. Valid values: `ios`, `android`, `linux`, `win`, and `other.`
`ip`	String	The IP address of the user who logs in to the app.
`host`	String	The domain name assigned by the Chat service to access RESTful APIs.
`appkey`	String	The key of the app. The unique identifier assigned to each app by the Chat service.
`user`	String	The ID of the user. The unique identifier of each user in the Chat app, in the format of `{appKey}/{OS}_{deviceId}`.
`version`	String	The version of the Chat SDK.
`timestamp`	Long	The Unix timestamp when the Chat server receives the login request, in milliseconds.
`status`	String	The current status of the user. `online` indicates that the user is online.

Log out of the app voluntarily

When a user logs out of the Chat app, the Chat server sends a callback to your app server. The sample code is as follows:

{
    "callId":"XXXX#XXXX25b54a81-1376-4669-bb3d-178339a8f11b",
    "reason":"logout",
    "security":"XXXXd77eXXXXf26801627fdaadca987e",
    "os":"ios",
    "ip":"223.71.97.198:4XXXX",
    "host":"********",
    "appkey":"XXXX#XXXX",
    "user":"XXXX#XXXXtstXXXX/ios_XXXX0737-db3a-d2b5-da18-b604XXXX195b",
    "version":"3.8.9.1",
    "timestamp":1642648914742,
    "status":"offline"
}

Field	Data Type	Description
`callId`	String	The ID of the callback. The unique identifier assigned to each callback, in the format of `{appKey}_{uuid}`, where the value of `uuid` is randomly generated.
`reason`	String	The reason that triggers the callback. `logout` indicates that a user logs out of the app.
`security`	String	The signature in the callback request used to confirm whether this callback is sent from the Chat server. The signature is the MD5 hash of the `{callId} + {secret} + {timestamp}` string, where the value of `secret` can be found on Agora Console.
`os`	String	The operating system of the device. Valid values: `ios`, `android`, `linux`, `win`, and `other.`
`ip`	String	The IP address of the user who logs out of the app.
`host`	String	The domain name assigned by the Chat service to access RESTful APIs.
`appkey`	String	The key of the app. The unique identifier assigned to each app by the Chat service.
`user`	String	The ID of the user. The unique identifier of each user in the Chat app, in the format of `{appKey}/{OS}_{deviceId}`.
`version`	String	The version of the Chat SDK.
`timestamp`	Long	The Unix timestamp when the Chat server receives the logout request, in milliseconds.
`status`	String	The current status of the user. `offline` indicates that the user is offline.

Log out of the app passively

When a user logs out of the Chat app due to being kicked out by another device, the Chat server sends a callback to your app server. The sample code is as follows:

{
    "callId":"XXXX#XXXX260ae3eb-ba31-4f01-9a62-8b3b05f3a16c",
    "reason":"replaced",
    "security":"XXXX00b1XXXX4fe76dbfdc664cbaa76b",
    "os":"ios","ip":"223.71.97.198:52709",
    "host":"msync@ebs-ali-beijing-msync40",
    "appkey":"XXXX#XXXX",
    "user":"XXXX#XXXXtst01XXXX/ios_XXXX01fd-b5a4-84d5-ebeb-bf10XXXX0442",
    "version":"3.8.9.1",
    "timestamp":1642648955563,
    "status":"offline"
}

Field	Data Type	Description
`callId`	String	The ID of the callback. The unique identifier assigned to each callback, in the format of `{appKey}_{uuid}`, where the value of `uuid` is randomly generated.
`reason`	String	The reason that triggers the callback. `replaced` indicates that a user logs out of the app due to being kicked out by another device.
`security`	String	The signature in the callback request used to confirm whether this callback is sent from the Chat server. The signature is the MD5 hash of the `{callId} + {secret} + {timestamp}` string, where the value of `secret` can be found on Agora Console.
`os`	String	The operating system of the device. Valid values: `ios`, `android`, `linux`, `win`, and `other.`
`ip`	String	The IP address of the user.
`host`	String	The domain name assigned by the Chat service to access RESTful APIs.
`appkey`	String	The key of the app. The unique identifier assigned to each app by the Chat service.
`user`	String	The ID of the user. The unique identifier of each user in the Chat app, in the format of `{appKey}/{OS}_{deviceId}`.
`version`	String	The version of the Chat SDK.
`timestamp`	Long	The Unix timestamp when the Chat server receives the logout request, in milliseconds.
`status`	String	The current status of the user. `offline` indicates that the user is offline.

Message events

Send a message

When a user sends a message in a one-to-one chat, chat group, or chat room of the Chat app, the Chat server sends a callback to your app server. The sample code is as follows:

{
    "callId":"{appkey}_{uuid}",
    "eventType":"chat_offline",
    "timestamp":1600060847294,
    "chat_type":"groupchat", 
    "group_id":"1693XXXX238921545",
    "from":"user1",
    "to":"user2",
    "msg_id":"8924XXXX42322",
    "payload":{
    // The details of the callback.
    },
    "securityVersion":"1.0.0",
    "security":"XXXX2c39XXXX9e7abc83958bcc3156d3"
}

Field	Data Type	Description
`callId`	String	The ID of the callback. The unique identifier assigned to each callback, in the format of `{appKey}_{uuid}`, where the value of `uuid` is randomly generated.
`eventType`	String	The message type of the callback. `chat`: Uplink messages. The messages that are about to be sent by the Chat server to end devices. `chat_offline`: Offline messages. The messages that are not sent by the Chat server as end users are offline.
`timestamp`	Long	The Unix timestamp when the Chat server receives the callback event, in milliseconds.
`chat_type`	String	The type of chat. `chat`: One-to-one chats. `groupchat`: Chat groups and chat rooms.
`group_id`	String	The ID of the chat group or chat room where the message is sent. This field only exists if `chat_type` is set to `groupchat`.
`from`	String	The sender of the message.
`to`	String	The recipient of the message.
`msg_id`	String	The message ID of the callback event. This ID is the same as the `msg_id` when the message is sent.
`payload`	Object	The structure of the callback event. This field varies according to the type of the message sent in a one-to-one chat, chat group, or chat room. See payload example below for details.
`securityVersion`	String	This parameter is reserved for future use.
`security`	String	The signature in the callback request used to confirm whether this callback is sent from the Chat server. The signature is the MD5 hash of the `{callId} + {secret} + {timestamp}` string, where the value of `secret` can be found on Agora Console.
`appkey`	String	The key of the app. The unique identifier assigned to each app by the Chat service.
`host`	String	The domain name assigned by the Chat service to access RESTful APIs.

Send a text message

When a user sends a text message in a one-to-one chat, chat group, or chat room, the Chat server sends a callback to your app server. The sample code of the payload field is as follows:

"payload":
{
    "ext":{},
    "bodies":[
        {
            "msg":"rr",
            "type":"txt"
        }
    ]
}