Messagerie

Un hôte qui travaille depuis votre logiciel doit voir les messages de ses voyageurs Localoge, et pouvoir leur répondre sans ouvrir notre site. Trois briques :

• le webhook message.received, qui vous prévient ;
• GET /reservations/{id}/messages, qui rend l’historique ;
• POST /reservations/{id}/messages, qui répond.

{id} accepte les deux identifiants : le nôtre (reservation_id, celui des webhooks et de message.received) ou le vôtre (external_reservation_id, pour un séjour que vous nous avez envoyé).

Portées : messages:read pour lire, messages:write pour écrire.

Le seul endroit de l’API où du texte écrit par une personne traverse

Tout le reste de l’API échange des dates, des montants et des identifiants. Ici, c’est la parole d’un voyageur ou d’un hôte. Vous êtes responsable de ce que vous en faites : ne l’exposez qu’à l’hôte concerné, ne l’utilisez à aucune autre fin, et ne le conservez pas au-delà du besoin.

Être prévenu : message.received

{
  "event": "message.received",
  "event_key": "message:3f8a…:1759140000000",
  "created_at": "2026-09-29T10:00:00.000Z",
  "api_version": "v1",
  "environment": "production",
  "data": {
    "external_property_id": "PROP-4821",
    "reservation_id": "3f8a…",
    "from": "guest",
    "text": "Bonjour, peut-on arriver vers 18 h ?",
    "sent_at": "2026-09-29T10:00:00.000Z"
  }
}

reservation_id est l’identifiant Localoge du séjour. Il vaut null quand le message précède toute réservation (une question posée depuis la fiche du logement). from vaut guest ou host.

Lire la conversation

curl https://localoge.com/api/v1/channel/reservations/RES-99001/messages \
  -H "Authorization: Bearer $LOCALOGE_KEY"

{
  "success": true,
  "environment": "production",
  "data": {
    "messages": [
      { "id": "a1…", "from": "guest", "text": "Bonjour, peut-on arriver vers 18 h ?", "sent_at": "2026-09-29T10:00:00.000Z" },
      { "id": "b2…", "from": "host", "text": "Oui, sans souci.", "sent_at": "2026-09-29T10:04:12.000Z" }
    ]
  }
}

• L’identifiant dans l’URL est reservation_id (le nôtre) ou external_reservation_id (le vôtre).
• Les messages sont rendus du plus ancien au plus récent, les 100 derniers au plus.
• Seuls les messages de ce séjour sont rendus : ceux échangés entre ce voyageur et cet hôte sur ce logement. Jamais la conversation d’un autre voyageur du même logement.
• Aucun nom, aucune adresse : from suffit à afficher la conversation.

Les séjours concernés

Les séjours vendus sur Localoge pour vos logements, retrouvés par leur reservation_id, et ceux que vous nous avez envoyés (POST /reservations), retrouvés par l’un ou l’autre identifiant. Un identifiant inconnu, ou un séjour qui ne concerne pas vos logements, répond 404 RESERVATION_NOT_FOUND.

Répondre au voyageur

curl -X POST https://localoge.com/api/v1/channel/reservations/RES-99001/messages \
  -H "Authorization: Bearer $LOCALOGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Oui, sans souci. Le code de la boîte à clés vous sera envoyé la veille." }'

{ "success": true, "environment": "production", "data": { "id": "c3…", "sent_at": "2026-09-29T10:05:00.000Z" } }

Code	Situation
201	Message posé.
400 INVALID_PAYLOAD	text absent, vide, ou de plus de 4000 caractères.
404 RESERVATION_NOT_FOUND	Cet identifiant de séjour n’existe pas chez nous.

Le message apparaît au voyageur comme venant de l’hôte, jamais de votre logiciel : c’est l’hôte qu’il a choisi, c’est à lui qu’il écrit. Écrivez donc à la première personne de l’hôte.

Qui est prévenu dépend de l’origine du séjour :

Séjour	Le voyageur est prévenu ?
Vendu sur Localoge (origin: "localoge")	Oui : en temps réel s’il a Localoge ouvert, par notification sur son téléphone et par e-mail.
Envoyé par vous (origin: "partner")	Non. Le message est rangé dans la conversation, mais rien ne lui est envoyé : c’est votre canal qui le connaît et lui écrit.

En sandbox

Le simulateur fait écrire un voyageur fictif ("event": "message.received") : vous recevez le webhook, puis vous répondez. La notification que le voyageur aurait reçue par e-mail arrive dans la boîte de test.