Listings APIListings API
Accedi

Rispondi alle recensioni e modifica o archivia una risposta

Trova recensioni a cui il proprietario può rispondere, rispondi e verifica l’arrivo alla piattaforma di pubblicazione, poi modifica o archivia la risposta.

Una risposta del proprietario viene pubblicata sulla piattaforma di pubblicazione per tuo conto. L'API la accetta subito e la invia in modo asincrono; la sequenza è: scegli una recensione a cui è possibile rispondere, pubblica la risposta, poi verificane l'esito rileggendo la recensione.

1. Scegli le recensioni a cui è possibile rispondere

Elenca le recensioni della sede e mantieni quelle in cui canRespond è true e responded è false. Il filtro responseStatus=["PENDING"] esegue il secondo controllo lato server; il valore JSON deve essere codificato per l'URL, operazione gestita da --data-urlencode.

Answerable reviews
curl -G "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/reviews" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'responseStatus=["PENDING"]' \--data-urlencode 'first=25'
JSON
{  "node": {    "id": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",    "source": "maps.google.com",    "rating": 5,    "content": "nice place for family together",    "responded": false,    "responseCount": 0,    "canRespond": true  }}

canRespond è false per le fonti che non accettano risposte del proprietario tramite l'API. Salta queste recensioni; un tentativo di risposta non raggiungerà la piattaforma di pubblicazione. Per preparare una bozza, Elenca le frasi delle recensioni ti indica ciò che i clienti menzionano più spesso, così puoi affrontarlo nella risposta.

2. Pubblica una risposta

POST /locations/reviews/respond accetta i campi direttamente nel corpo, senza racchiuderli in input. interactionId è il valore di id della recensione. respondedWith è facoltativo e indica il nome di un modello di risposta, se ne hai usato uno.

Respond
curl -X POST https://listingsapi.com/api/v4/locations/reviews/respond \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "interactionId": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",  "responseContent": "Thank you for visiting Jenny Home: we are glad you enjoyed your experience!"}'
JSON
{  "data": {    "respondToInteraction": {      "interaction": {        "id": "2090753a-ece6-4837-8336-8494ad308523",        "interactionId": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",        "content": "Thank you for visiting Jenny Home: we are glad you enjoyed your experience!",        "interactionStatus": "CREATED",        "editedResponse": false      },      "errors": null    }  }}

Conserva interaction.id: è il valore di responseId che ti serve per modificare o archiviare la risposta in seguito. Una risposta rifiutata viene restituita come 200 con errors valorizzato all'interno di data.respondToInteraction, quindi leggi il corpo. In questo caso gli SDK sollevano ValidationError.

3. Verifica che sia arrivata alla piattaforma di pubblicazione

interactionStatus inizialmente è CREATED e avanza senza ulteriori chiamate. Dopo una breve attesa, rileggi la recensione tramite il suo ID e controlla responded, responseCount e lo stato della risposta all'interno di responses[].

StatoSignificato
CREATEDAccettata e messa in coda per la piattaforma di pubblicazione.
COMPLETEDPubblicata sulla piattaforma di pubblicazione. Alcune piattaforme si fermano qui.
CONFIRMEDPubblicata e confermata dalla piattaforma di pubblicazione.
FAILEDLa piattaforma di pubblicazione l'ha rifiutata. Il campo remarks della risposta ne indica il motivo.
Re-read
curl -G "https://listingsapi.com/api/v4/reviewDetails" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'interactionIds=["9e26d2a8-a6ed-42ea-8454-47d1c92ea841"]'
JSON
{  "id": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",  "responded": true,  "responseCount": 1,  "responses": [    {      "id": "2090753a-ece6-4837-8336-8494ad308523",      "content": "Thank you for visiting Jenny Home: we are glad you enjoyed your experience!",      "interactionStatus": "CONFIRMED",      "editedResponse": false    }  ]}

responded: true con una risposta in stato CONFIRMED o COMPLETED significa che il cliente può vederla. Se vedi FAILED, leggi il campo remarks della risposta per conoscere il motivo fornito dalla piattaforma di pubblicazione prima di riprovare.

4. Modifica una risposta

POST /locations/reviews/respond/edit richiede entrambi gli ID: reviewId è quello della recensione, responseId è quello della risposta del passaggio 2. La modifica viene inviata nuovamente, quindi il valore di interactionStatus della risposta torna a CREATED e editedResponse diventa true quando la modifica arriva a destinazione.

Edit reply
curl -X POST https://listingsapi.com/api/v4/locations/reviews/respond/edit \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "reviewId": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",  "responseId": "2090753a-ece6-4837-8336-8494ad308523",  "responseContent": "Thank you again: we have updated our reply to include our new store hours."}'
JSON
{  "data": {    "editResponse": {      "status": "true",      "reviewId": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",      "responseId": "2090753a-ece6-4837-8336-8494ad308523"    }  }}

status è la stringa "true" quando la modifica viene accettata. Verifica il nuovo testo come al passaggio 3.

5. Archivia una risposta

POST /locations/reviews/respond/archive accetta solo responseId. L'archiviazione rimuove la risposta da responses dell'interazione in Listings API. Non ritira una risposta già pubblicata su Google o Facebook, quindi usala per eliminare una bozza il cui invio non è riuscito o che è stata sostituita, e usa la modifica per qualsiasi risposta pubblicata.

Archive reply
curl -X POST https://listingsapi.com/api/v4/locations/reviews/respond/archive \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "responseId": "2090753a-ece6-4837-8336-8494ad308523" }'
JSON
{  "data": {    "archiveResponse": {      "status": "true"    }  }}

Dopo l'archiviazione, il valore di responseCount della recensione diminuisce e responded riflette le risposte rimanenti.

6. Ricevi gli eventi delle risposte tramite webhook

Un evento interaction.response viene generato quando una risposta viene pubblicata, modificata o archiviata. Il payload si trova in data.interaction, con type: "Response" e parent_id impostati sull'ID della recensione, così puoi associarlo al tuo record senza un'altra chiamata. Come per interaction.review, il suo location_id non è normalizzato e può essere null. La configurazione è descritta in Reagisci agli eventi con i webhook.

Passaggi successivi