Répondre aux avis, puis modifier ou archiver une réponse

Trouvez les avis acceptant une réponse du propriétaire, publiez-la, vérifiez sa réception sur la plateforme de publication, modifiez-la ou archivez-la.

Une réponse du propriétaire est publiée sur la plateforme de publication en votre nom. L'API l'accepte immédiatement et la transmet de manière asynchrone ; la procédure est la suivante : choisissez un avis auquel vous pouvez répondre, publiez la réponse, puis confirmez sa publication en consultant à nouveau l'avis.

1. Choisir les avis auxquels vous pouvez répondre

Listez les avis de l'établissement et conservez ceux dont canRespond vaut true et responded vaut false. Le filtre responseStatus=["PENDING"] effectue la deuxième vérification côté serveur ; la valeur JSON doit être encodée pour l'URL, ce que prend en charge --data-urlencode.

curl -G "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/reviews" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'responseStatus=["PENDING"]' \--data-urlencode 'first=25'

{  "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 vaut false pour les sources qui n'acceptent pas les réponses du propriétaire via l'API. Ignorez ces avis ; toute tentative de réponse ne parviendra pas à la plateforme de publication. Pour la rédaction, Lister les expressions des avis vous indique ce que les clients mentionnent le plus souvent, afin que vous puissiez en tenir compte dans votre réponse.

2. Publier une réponse

POST /locations/reviews/respond accepte les champs directement dans le corps, sans les envelopper dans input. interactionId correspond au champ id de l'avis. respondedWith est facultatif et indique le nom d'un modèle de réponse si vous en avez utilisé un.

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!"}'

{  "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    }  }}

Conservez interaction.id : il s'agit du champ responseId dont vous aurez besoin pour modifier ou archiver la réponse ultérieurement. Une réponse rejetée est renvoyée sous la forme 200 avec errors renseigné dans data.respondToInteraction ; lisez donc le corps. Les SDK lèvent ValidationError dans ce cas.

3. Confirmer que la réponse est parvenue à la plateforme de publication

interactionStatus vaut initialement CREATED et évolue sans appels supplémentaires. Après une courte attente, récupérez à nouveau l'avis à l'aide de son identifiant et vérifiez responded, responseCount et le statut de la réponse dans responses[].

curl -G "https://listingsapi.com/api/v4/reviewDetails" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'interactionIds=["9e26d2a8-a6ed-42ea-8454-47d1c92ea841"]'

{  "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 avec une réponse au statut CONFIRMED ou COMPLETED signifie que le client peut la voir. Si vous voyez FAILED, lisez le champ remarks de la réponse pour connaître le motif fourni par la plateforme de publication avant de réessayer.

4. Modifier une réponse

POST /locations/reviews/respond/edit nécessite les deux identifiants : reviewId correspond à l'avis, responseId à la réponse de l'étape 2. La modification est soumise à nouveau ; le champ interactionStatus de la réponse repasse donc à CREATED et editedResponse devient true une fois la modification transmise.

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."}'

{  "data": {    "editResponse": {      "status": "true",      "reviewId": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",      "responseId": "2090753a-ece6-4837-8336-8494ad308523"    }  }}

status est la chaîne "true" lorsque la modification est acceptée. Confirmez la nouvelle formulation de la même manière qu'à l'étape 3.

5. Archiver une réponse

POST /locations/reviews/respond/archive accepte uniquement responseId. L'archivage supprime la réponse du champ responses de l'interaction dans Listings API. Il ne retire pas une réponse déjà publiée sur Google ou Facebook ; utilisez-le donc pour supprimer un brouillon dont la publication a échoué ou qui a été remplacé, et utilisez la modification pour toute réponse publiée.

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" }'

{  "data": {    "archiveResponse": {      "status": "true"    }  }}

Après l'archivage, le champ responseCount de l'avis diminue et responded reflète les réponses restantes.

6. Recevoir les événements relatifs aux réponses par webhook

Un événement interaction.response est déclenché lorsqu'une réponse est publiée, modifiée ou archivée. La charge utile se trouve sous data.interaction, avec type: "Response" et parent_id définis sur l'identifiant de l'avis, ce qui vous permet de l'associer à votre propre enregistrement sans appel supplémentaire. Comme pour interaction.review, son champ location_id n'est pas normalisé et peut valoir null. La configuration est décrite dans Réagir aux événements avec des webhooks.

Étapes suivantes

• Récupérer les avis : constituez la file d’attente des avis en attente de traitement dans l’ensemble du compte.
• Analyse des avis : suivez review-response-rate à mesure que vous traitez la file d’attente.
• Référence : Répondre à une interaction, Modifier une réponse, Archiver une réponse, Attributs d’une interaction.
• SDK : Avis avec Python, Avis avec Node.