Handle an appointment request
POST/v1/agent/appointments/:appointmentId
Performs one staff action for an appointment owned by the application. The application API key determines ownership; unknown and cross-application appointment IDs both return APPOINTMENT_NOT_FOUND. Reusing the same Idempotency-Key with the same body replays the stored response. Idempotency-Key is unique across the application: retries must keep the same appointment, effective action and request body. Reuse for another target/action/body returns 400 INVALID_APPOINTMENT_ACTION_PAYLOAD. Use a new key for each new action.
Request
Responses
- 200
- 400
- 401
- 404
Durable action result. Customer message delivery is independent. A successful staff confirmation may append a safe Google Calendar template URL to the configured customer message; delivery failure never reverses the appointment transition.
IDEMPOTENCY_KEY_REQUIRED, INVALID_APPOINTMENT_ACTION_PAYLOAD (including incompatible key reuse), APPOINTMENT_VERSION_CONFLICT, APPOINTMENT_STATE_CONFLICT, APPOINTMENT_SLOT_UNAVAILABLE, APPOINTMENT_ANSWERS_INVALID, APPOINTMENT_CALENDAR_BUSY, APPOINTMENT_CONVERSATION_NOT_APPLICABLE, or APPOINTMENT_ACTION_FAILED. Review validation before retrying. Customer notification failures are reported independently in messageDelivery.
Missing, invalid, expired, or deleted application API key.
APPOINTMENT_NOT_FOUND.