The Callback URL

The Callback URL is defined in your API Settings page. It's used by the StreamAPI system to notify you of events and actions. One of the primary uses is for authenticating users when they want to enter into a stream as a chatter. The authentication credentials (such as username/password) are sent to you for approval. It's also used to notify you when other events occur.

The Callback URL lives on your server. Typically it's something like http://yoursite.com/streamapi/callback, but any URL we can reach is fine.

Every callback request will include a action parameter. This action specifies the type of callback request being made.

Your responses must be in the XML format specified for each action type.

Currently, StreamAPI provides 3 different types of callbacks where it can notify you different events that your users are doing in live session:

•   Authentication (action = login)
•   End Live Session (action = end_live)
•   End Recorded Session (action = end_record)

1.)  Authentication (action = login)

Action : login

Description

This is used when a user clicks an "Enter chat" button. Credentials will be sent from the Flash interface to your callback URL with the action parameter set to "login".

Method

POST

Parameters

• action
• public_hostid

And either

• username
• password

or

• key

Typically you will either lookup the username/password or key (if used instead) in your database and then authorize them to enter the chat session or not. Any response code other than 0 is considered an authentication failure. The message tag allows you to tell a user why they were refused entry ("Username and password did not match" for example).

Example request

POST http://yoursite.com/streamapi/callback action=login username=jim@theoffice.com password=dwightrocks public_hostid=12345

username

The username entered by the user attempting to login from the Flash interface. This is not sent if using "key" parameter.

password

The password entered by the user attempting to login from the Flash interface. This is not sent if using "key" parameter.

key

This is used as an authentication credential if specified by the Flash interface. It can be used as an alternative to standard username/password authentication, in scenarios where you want to offer a simple "password" or other simple token for access to a session.

public_hostid

This is the Public Host ID of the session host (owner). This is how you can identify which session a user is attempting to login to.

Your response

Authentication successful response (allowed entry)

	<?xml version="1.0" encoding="UTF-8" ?> 
	<response> 
		<user> 
			<name>MyCoolName</name> <role>cohost</role> 
		</user> 
		<code>0</code> 
	</response> 

role

The role tag allows you to specify the group that a user is in. In the Theme Editor you can restrict access to components based on a user's role. For example only allowing users in the "cohost" role to have access to the Guest Cam component.

Authentication failed response (disallowed entry)

	<?xml version="1.0" encoding="UTF-8" ?> 
	<response> 
		<code>8</code> <message>authentication failed</message> 
	</response> 

For a more detailed explanation and how-to for authentication call back, check out the view and join live session documentation.

2.)  End Live Session (action = end_live)

Action : end_live

Description

This is used when a host closes his live session window or ends his session. With this callback type, streamAPI notifies you that a live session has just ended.

Method

POST

Parameters

• action
• public_hostid
• channel_id
• duration
• viewers
• max_viewers

Example request

POST http://www.yourdomain.com/callback?action=end_live&public_hostid=12345&channel_id=6789538&duration=50&viewers=100&max_viewers=10

public_hostid

This is the Public Host ID of the session host (owner).

channel_id

This is the unique id of a host's session.

duration

Amount of time that a host was in live session (in minutes).

viewers

Total number of viewers in the live session

max_viewers

Maximum number of concurrent viewers in the live session

Your response

Sucessful end live session call

	<?xml version="1.0" encoding="UTF-8" ?> 
	<response> 
		<code>0</code> 
	</response> 

Failed end live session call

	<?xml version="1.0" encoding="UTF-8" ?> 
	<response> 
		<code>8</code>
	</response> 

3.)  End Record(action = end_record)

Action : end_record

Description

This is used when a host finishes recording a live session and that the video has also finished recording. With this callback type, streamAPI notifies you that a live video recording has finished its conversion.

Method

POST

Parameters

• action
• public_hostid
• channel_id
• duration
• filename
• url

Example request

POST http://www.yourdomain.com/callback?action=end_record&duration=50&public_hostid=12345&channel_id=6789538&filename=6a4415c67335759d2a5af656ec25f9aac822f63a_1242074406318.flv&url=http://static.streamapi.com/video/100/000/074/0/6a4415c67335759d2a5af656ec25f9aac822f63a_1242074406318.flv

public_hostid

This is the Public Host ID of the session host (owner).

channel_id

This is the unique id of a host's live session that was recorded.

duration

Amount of time of the recorded video in seconds

filename

The file name of the recorded video in .flv

url

URL path of the recorded video

Your response

Sucessful end record call

	<?xml version="1.0" encoding="UTF-8" ?> 
	<response> 
		<code>0</code> 
	</response> 

Failed end record call

	<?xml version="1.0" encoding="UTF-8" ?> 
	<response> 
		<code>8</code>
	</response>