Listings APIListings API
Entrar

Responda a avaliações e depois edite ou arquive uma resposta

Encontre avaliações que aceitam resposta do proprietário, responda, confirme o recebimento na plataforma de publicação e edite ou arquive a resposta.

Uma resposta do proprietário é publicada na plataforma de publicação em seu nome. A API a aceita imediatamente e a entrega de forma assíncrona; a sequência é: escolher uma avaliação que possa ser respondida, publicar a resposta e depois confirmar com uma nova consulta.

1. Selecione avaliações que possam ser respondidas

Liste as avaliações do local e mantenha aquelas em que canRespond é true e responded é false. O filtro responseStatus=["PENDING"] faz a segunda verificação no servidor; o valor JSON precisa ser codificado para URL, o que é feito por --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 para fontes que não aceitam respostas do proprietário pela API. Ignore essas avaliações; uma tentativa de resposta não chegará à plataforma de publicação. Para elaborar o texto, Liste frases de avaliações informa o que os clientes mais mencionam, para que uma resposta possa abordar esses pontos.

2. Publique uma resposta

POST /locations/reviews/respond recebe os campos diretamente no corpo, sem envolvê-los em input. interactionId é o id da avaliação. respondedWith é opcional e indica o nome de um modelo de resposta, caso você tenha usado um.

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

Guarde interaction.id: esse é o responseId de que você precisa para editar ou arquivar a resposta depois. Uma resposta rejeitada retorna como 200 com errors preenchido dentro de data.respondToInteraction, então leia o corpo. Os SDKs lançam ValidationError nesse caso.

3. Confirme que a resposta chegou à plataforma de publicação

interactionStatus é CREATED inicialmente e avança sem chamadas adicionais. Consulte a avaliação novamente pelo id após uma breve espera e verifique responded, responseCount e o status da resposta dentro de responses[].

StatusSignificado
CREATEDAceita e colocada na fila para a plataforma de publicação.
COMPLETEDPublicada na plataforma de publicação. Algumas plataformas param aqui.
CONFIRMEDPublicada e confirmada pela plataforma de publicação.
FAILEDA plataforma de publicação a rejeitou. remarks na resposta informa o 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 com uma resposta CONFIRMED ou COMPLETED significa que o cliente pode vê-la. Se você vir FAILED, leia remarks na resposta para saber o motivo informado pela plataforma de publicação antes de tentar novamente.

4. Edite uma resposta

POST /locations/reviews/respond/edit precisa dos dois ids: reviewId é o da avaliação, e responseId é o da resposta da etapa 2. A edição é reenviada, então o campo interactionStatus da resposta volta a CREATED e editedResponse passa a ser true quando ela chega à plataforma de publicação.

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 é a string "true" quando a edição é aceita. Confirme o novo texto da mesma forma que na etapa 3.

5. Arquive uma resposta

POST /locations/reviews/respond/archive recebe apenas responseId. O arquivamento remove a resposta de responses da interação na Listings API. Ele não retira uma resposta que já esteja publicada no Google ou no Facebook, então use-o para remover um rascunho cujo envio falhou ou que foi substituído, e use a edição para qualquer resposta publicada.

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

Após o arquivamento, o valor de responseCount da avaliação diminui e responded reflete as respostas restantes.

6. Receba eventos de resposta por webhook

Um evento interaction.response é disparado quando uma resposta é publicada, editada ou arquivada. O payload fica em data.interaction, com type: "Response" e parent_id definidos como o id da avaliação, para que você possa associá-lo ao seu próprio registro sem outra chamada. Assim como em interaction.review, seu location_id não é normalizado e pode ser null. A configuração está em Reaja a eventos com webhooks.

Próximos passos