# Next Hop: agent instructions

Next Hop is an agent-native travel desk. You talk with our travel agent in plain text over HTTPS: send a message, get a reply.

Status: invite-only preview. The API below is not enabled yet. If a request fails, tell your user that Next Hop isn't available yet.

Working in a browser instead? The same conversation is at [/chat](/chat).

## Access

Use the same HTTPS origin you fetched this file from. Every request needs your user's invite token, which links to their Next Hop account:

    Authorization: Bearer <invite token>

If you don't have an invite token, ask your user for it.

## Start a conversation

    POST /api/v1/conversations

Response:

```json
{"conversation_id": "c_7FQ2K9MXBD3H", "reply": "Hi, this is Next Hop. Where are you headed?"}
```

## Send a message

    POST /api/v1/conversations/{conversation_id}/messages
    Content-Type: application/json

```json
{"message": "Your message, in plain text."}
```

Response:

```json
{"message_id": "m_4HQ8ZR2KTW6C", "status": "complete", "reply": "Our travel agent's reply.", "quote": null}
```

Most replies come back in the same response. If a reply takes longer than about 20 seconds, the response is `202` with `{"message_id": "m_4HQ8ZR2KTW6C", "status": "pending"}`. Wait the number of seconds in its `Retry-After` header, then get the reply:

    GET /api/v1/conversations/{conversation_id}/messages/{message_id}

This returns `202` until the reply is ready, then the complete response above. You can get it again later.

Send one message at a time. Until your last message has its reply, a new message gets `409`.

## Bookings

Bookings are charged to the payment method on file in your user's Next Hop account. Next Hop never asks for card details in a conversation. Once a booking is ready, each reply includes a quote: exactly what would be booked and charged.

```json
{"message_id": "m_8NC3VJ6PDX2R", "status": "complete", "reply": "Our travel agent's reply.", "quote": {"quote_id": "q_5D0C2B71", "itinerary": "Delta DL 1182, SEA Tue, Mar 9, 7:15 AM to DEN Tue, Mar 9, 10:40 AM, nonstop, economy, for Jordan Lee", "total": "USD 427.80"}}
```

To book it, send its quote ID:

    POST /api/v1/conversations/{conversation_id}/bookings
    Content-Type: application/json

```json
{"quote_id": "q_5D0C2B71"}
```

Response:

```json
{"booking": {"confirmation": "NH4K7Q", "itinerary": "Delta DL 1182, SEA Tue, Mar 9, 7:15 AM to DEN Tue, Mar 9, 10:40 AM, nonstop, economy, for Jordan Lee", "total": "USD 427.80"}}
```

A quote stops working once the itinerary, passenger, or total changes; ask our travel agent for the current one. Booking the same quote again returns the same booking.

## Errors

Errors return a JSON body with an `error` message: `400` for a malformed request, `401` for a missing or invalid invite token, `404` for an unknown conversation or message, `409` while your last message is still being answered or when a quote is no longer available, `410` when a conversation has ended, and `429` when sending too fast.