You can add an HTTP REST request to your service in the Info View. When the listener chooses the HTTP request action, Sonos sends an HTTP request using your given URL and HTTP method. Your service’s response back to Sonos can be a simple success response, an error response, or a more complex response that Sonos uses to modify the custom actions displayed in the Info View.

The example in this section shows how to save an item to your service’s favorites. For a complete favorites implementation, see Add favorites.

The following steps describe how to implement an HTTP request action.

1. Define text strings for the HTTP request action
2. Respond to getExtendedMetadata requests from Sonos
3. Implement the REST method on your service
4. Respond back to Sonos for the HTTP request

---

Define HTTP request action text strings

Define the text string in your strings.xml file that displays for the HTTP request action in the Info View of the Sonos app. For this example we use, “Save to My Acme Music”. Also define any error strings that might be needed.

---

Respond to getExtendedMetadata requests

When the listener selects the ellipsis (…) to see the Info View, Sonos sends your service a getExtendedMetadata request. This example is for a track item.

When your service responses to getExtendedMetadata, include all the custom action items for the Info View. To simplify this example we’ll show only one HTTP request.

The action sub-elements for an HTTP request action include the following. See SMAPI object types for details.

Element	Description
id	A unique ID for this action.
title	The SAVE_MUSIC value corresponds to the stringId value in the strings.xml file above.
actionType	This value for an HTTP request action must be simpleHttpRequest.
simpleHttpRequestAction	This contains the following sub-elements: url – the URL of the HTTP request Sonos will send if the listener selects this HTTP request action from the Info View. method – The HTTP method to execute. Valid values are the standard methods POST, GET, PUT, or DELETE. (Optional) httpHeaders – Custom HTTP headers can be added to the HTTP request by including name/value pairs in httpHeader sub-elements. (Optional) refreshOnSuccess – Include a value of trueto cause Sonos to update the container the listener is browsing after the HTML request successfully executes.
failureMessageStringId successMessageStringId	(Optional) you can supply stringIdvalues for failureMessageStringId and successMessageStringId that Sonos displays to the listener depending on the execution results of the HTTP request. Note, values for these can be overwritten by returning failureMessageStringId and successMessageStringId JSON values in your response back to Sonos for the HTTP REST request.

---

Implement the REST method on your service

If the listener chooses the HTTP request action from the Info View, Sonos sends the HTTP request using the given method and URL. Sonos includes the current SMAPI authentication token in an Authorization header as an OAuth Bearer token. Note, you cannot use custom httpHeaders to attempt to overwrite the Authorization header. For more about authentication, authorization, and tokens, see Use authentication tokens.

The following is an example HTTP REST request from Sonos:

Your service provides the implementation. For this example you would add the track to this listener’s favorites list on your service.

---

Respond back to Sonos for the HTTP request

In your response to the HTTP request back to Sonos, you can supply optional string IDs in JSON format that identify messages Sonos displays to the listener depending on the success or failure execution of the HTTP request. You can also supply more complex JSON objects that Sonos uses to modify the Info View the listener sees.

Success responses

For a basic success response, you can supply an optional stringId value in a successMessageStringId JSON object that identifies a string in your strings.xml file. Note, if you return successMessageStringId here, it overrides the value if previously supplied in the successMessageStringId XML element in your original getExtendedMetadata response that set up the HTTP request.

A simple JSON success response back to the Sonos app might look like this:

Failure responses

You can supply an optional stringId value in a failureMessageStringId JSON object that identifies a string in your strings.xml file. Note, if you return failureMessageStringId here, it overrides the value if previously supplied in the failureMessageStringId XML element in your original getExtendedMetadata response that set up the HTTP request.

A JSON failure example response back to the Sonos app might look like the following:

If the HTTP request results in a 401 error to Sonos, this may indicate that the authentication token has expired. Sonos will attempt to refresh the token by making a refreshAuthToken request to your service. If the token refresh succeeds, then Sonos will retry the original HTTP request with the new token in the Authorization header. Sonos will only retry the HTTP request once. If it fails again, Sonos will display the failure message. See Use authentication tokens for details.

Responses to change the Info View

To modify the listener’s Info View after the HTTP request, send a more complex JSON response to Sonos. For example, after adding a track to the listener’s favorites, you might want to change the “Save to My Acme Music” action to be the action “Remove from My Acme Music”, as shown below.

In the JSON response, return all of the actions that you want in the relatedActions object. The screen above shows two related actions:

• An HTTP request action, “Remove from My Acme Music”, implemented with a simpleHttpRequestAction object in the JSON response.
• An open URL action, “Concerts”, implemented with an openUrlAction object in the JSON response. See Web page for details.

All other custom actions in the Info View remain unchanged. Following is the associated JSON response.

For details of the relatedActions JSON array, see SMAPI object types.