API de réservation

Vue d'ensembleCopier le lien

L'API de réservation IA est un endpoint unique qu'un agent (une action ChatGPT, un bot vocal, un site partenaire, votre propre script) appelle pour prendre rendez-vous avec votre équipe :

https://app.asknudge.ai/api/ai

• Les lectures sont des requêtes GET avec un paramètre action.
• Les écritures sont des requêtes POST dont le corps JSON porte un champ action.
• Aucune clé d'API n'est nécessaire. On ne peut réserver que des créneaux proposés par Nudge, via des identifiants de créneau signés qui expirent au bout de 30 minutes.
• Les réponses portent Access-Control-Allow-Origin: *.

Un rendez-vous pris par cette API est un rendez-vous Nudge comme les autres : il arrive dans l'agenda de l'hôte avec un lien de visio, le contact reçoit l'e-mail de confirmation, votre équipe est prévenue, et le rendez-vous comme le contact sont enregistrés avec la source ai_api.

Avant de commencerCopier le lien

Parcours typeCopier le lien

1. GET  ?action=manifest            → règles, questions et durée
2. GET  ?action=get_availability    → créneaux avec un id signé (valable 30 min)
3. POST { action: "book", slot_id, email, … }
                                    → rendez-vous + cancel_url (gardez le jeton)
4. POST { action: "reschedule" | "cancel", booking_id, token, … }

Lire le manifesteCopier le lien

curl "https://app.asknudge.ai/api/ai?action=manifest&org=acme&form=demo-request"

{
  "booking_supported": true,
  "provider": "nudge",
  "version": "1.0",
  "api": {
    "url": "https://app.asknudge.ai/api/ai",
    "actions": ["get_availability", "get_available_dates", "get_booking_status", "book", "cancel", "reschedule"]
  },
  "form": {
    "name": "Book a demo",
    "description": "",
    "slug": "demo-request",
    "org": "acme",
    "url": "https://app.asknudge.ai/acme/demo-request",
    "languages": ["en", "fr"],
    "default_language": "en"
  },
  "booking": {
    "video_provider": "google_meet",
    "duration_minutes": 30,
    "buffer_minutes": 15,
    "min_notice_minutes": 60,
    "window_days": 14,
    "time_format": "24h",
    "allow_guests": true,
    "max_guests": 5
  },
  "required_fields": [
    { "name": "company", "label": "Company", "type": "text", "required": true }
  ],
  "ai_instructions": "Only book if the person is a decision-maker.",
  "consent_required": false,
  "consent_text": ""
}

Transmettez les réponses aux required_fields dans form_responses au moment de réserver. Quand consent_required vaut true, montrez consent_text à la personne avant de réserver.

Lister les jours disponiblesCopier le lien

curl "https://app.asknudge.ai/api/ai?action=get_available_dates&org=acme&form=demo-request&days=14"

{
  "form": { "name": "Book a demo", "slug": "demo-request" },
  "dates": [
    { "date": "2026-11-02", "has_bookings": false },
    { "date": "2026-11-03", "has_bookings": true }
  ]
}

Les dates sont des jours calendaires en UTC. has_bookings indique seulement si l'espace a déjà des rendez-vous ce jour-là ; cela ne veut pas dire que la journée est pleine. Utilisez get_availability pour savoir quels horaires sont libres.

Lire les disponibilitésCopier le lien

curl "https://app.asknudge.ai/api/ai?action=get_availability&org=acme&form=demo-request&date_from=2026-11-02&date_to=2026-11-06"

{
  "form": { "name": "Book a demo", "slug": "demo-request", "duration_minutes": 30 },
  "slots": [
    {
      "id": "eyJjIjoidG1fMnY1Yjhu….Xk3v…",
      "start": "2026-11-02T09:00:00.000Z",
      "end": "2026-11-02T09:30:00.000Z"
    }
  ],
  "timezone": "Europe/Paris",
  "required_fields": [
    { "id": "company", "label": "Company", "type": "text", "required": true, "mapping": null }
  ],
  "all_fields": []
}

Les disponibilités appliquent déjà tout ce que le formulaire et l'équipe définissent : horaires de travail, rendez-vous et événements d'agenda existants, délai minimum, tampons, limites journalières, fenêtre de réservation et rendez-vous collectifs. Si l'agenda d'un hôte ne peut pas être lu, cet hôte est écarté plutôt que de risquer une double réservation.

Réserver un rendez-vousCopier le lien

curl -X POST https://app.asknudge.ai/api/ai \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "action": "book",
    "org": "acme",
    "form": "demo-request",
    "slot_id": "eyJjIjoidG1fMnY1Yjhu….Xk3v…",
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+33612345678",
    "form_responses": { "company": "Example Inc." }
  }'

En-tête optionnel : Idempotency-Key (jusqu'à 255 caractères). Si vous rejouez un book avec une clé déjà utilisée avec succès sur cet espace, Nudge ne réserve pas deux fois et répond {"success": true, "duplicate": true}. Une clé dont la réservation a échoué est libérée : vous pouvez réessayer avec la même clé.

{
  "success": true,
  "booking": {
    "id": "bk_4n7q2w9e5r1t8y3a",
    "start_time": "2026-11-02T09:00:00.000Z",
    "end_time": "2026-11-02T09:30:00.000Z",
    "meet_link": "https://meet.google.com/abc-defg-hij",
    "video_provider": "google_meet"
  },
  "contact": { "id": "cnt_6h3j8k1m4n7p2q5r" },
  "cancel_url": "https://app.asknudge.ai/booking/bk_4n7q2w9e5r1t8y3a/cancel?token=…"
}

Conservez booking.id et le paramètre token de cancel_url : il vous faut les deux pour annuler ou déplacer le rendez-vous. Vous pouvez aussi donner cancel_url à la personne : il ouvre la page d'annulation de Nudge.

Chaque appel book crée un nouveau contact dans l'espace avec les informations envoyées.

Lire le statut d'un rendez-vousCopier le lien

curl "https://app.asknudge.ai/api/ai?action=get_booking_status&short_id=48213&token=…"

{
  "booking": {
    "short_id": "48213",
    "start_time": "2026-11-02T09:00:00.000Z",
    "end_time": "2026-11-02T09:30:00.000Z",
    "status": "scheduled",
    "meet_link": "https://meet.google.com/abc-defg-hij",
    "video_provider": "google_meet"
  }
}

Une référence inconnue et un mauvais jeton donnent la même réponse 404 Booking not found.

Annuler un rendez-vousCopier le lien

curl -X POST https://app.asknudge.ai/api/ai \
  -H "Content-Type: application/json" \
  -d '{ "action": "cancel", "booking_id": "bk_4n7q2w9e5r1t8y3a", "token": "…" }'

Réponse : {"success": true, "cancelled": true}. L'événement d'agenda est supprimé et l'hôte est prévenu. Erreurs : 404 rendez-vous inconnu, 403 mauvais jeton.

Déplacer un rendez-vousCopier le lien

Récupérez d'abord des disponibilités fraîches, puis envoyez le nouveau créneau :

curl -X POST https://app.asknudge.ai/api/ai \
  -H "Content-Type: application/json" \
  -d '{ "action": "reschedule", "booking_id": "bk_4n7q2w9e5r1t8y3a", "token": "…", "new_slot_id": "eyJj….Q2x…" }'

{
  "success": true,
  "booking": {
    "id": "bk_9c3v6b2n8m5k1j7h",
    "start_time": "2026-11-04T14:00:00.000Z",
    "end_time": "2026-11-04T14:30:00.000Z",
    "meet_link": "https://meet.google.com/xyz-abcd-efg"
  }
}

Nudge réserve d'abord le nouveau créneau et n'annule l'ancien qu'ensuite : un déplacement raté ne laisse jamais la personne sans rendez-vous. Le nouveau rendez-vous a un nouvel identifiant bk_ et son propre jeton, que cette réponse ne renvoie pas : le contact reçoit un nouvel e-mail de confirmation avec les liens pour le gérer.

Gérer un rendez-vous existantCopier le lien

Ces endpoints font tourner les pages « déplacer » et « annuler » de Nudge. Vous pouvez les appeler pour construire votre propre page autour d'un rendez-vous. {bookingId} est l'identifiant bk_.

Ces endpoints n'envoient pas d'en-têtes CORS : appelez-les depuis votre serveur ou depuis une page du même domaine.

Lire un rendez-vousCopier le lien

curl https://app.asknudge.ai/api/booking/bk_4n7q2w9e5r1t8y3a

Renvoie id, startTime, endTime, status (scheduled, cancelled, rescheduled, completed, no_show), meetLink, canReschedule, canCancel, depositPaid, contact (firstName, lastName, email), hostName, formName, formSlug, orgName, orgSlug, orgLogoUrl, orgWebsiteUrl, whiteLabel, display (brandColor, timeFormat, showHostAvatars, durationMinutes) et assistantEnabled. 404 not_found pour un identifiant inconnu.

Télécharger le fichier d'agendaCopier le lien

curl -o meeting.ics "https://app.asknudge.ai/api/booking/bk_4n7q2w9e5r1t8y3a/ics?token=…&lang=fr"

Renvoie du text/calendar. Sans jeton, le fichier contient le titre, l'horaire et le lien de visio. Avec un jeton valide, il contient aussi les liens pour déplacer et annuler, dans la langue indiquée par lang. Un mauvais jeton donne 403 token_invalid ; un rendez-vous qui n'est plus planifié donne 409 not_scheduled.

Lister les créneaux pour déplacer un rendez-vousCopier le lien

curl https://app.asknudge.ai/api/booking/bk_4n7q2w9e5r1t8y3a/slots

Renvoie slots (closer_id, start, end), duration, timezone, closers (id, name, initials, avatar_url), collective et window. Quand le formulaire garde le même hôte lors d'un déplacement, seuls les créneaux de cet hôte sont listés. 409 not_reschedulable si le rendez-vous ne peut plus être déplacé.

Déplacer un rendez-vousCopier le lien

curl -X POST https://app.asknudge.ai/api/booking/bk_4n7q2w9e5r1t8y3a/reschedule \
  -H "Content-Type: application/json" \
  -d '{ "token": "…", "start": "2026-11-04T14:00:00Z", "end": "2026-11-04T14:30:00Z" }'

Réponse : {"rescheduled": true, "booking": {"id": "bk_…", "startTime": "…", "meetLink": "…"}}. Nudge revérifie le créneau contre les disponibilités réelles avant de le réserver.

Annuler un rendez-vousCopier le lien

curl -X POST https://app.asknudge.ai/api/booking/bk_4n7q2w9e5r1t8y3a/cancel \
  -H "Content-Type: application/json" \
  -d '{ "token": "…", "reason": "Je ne peux plus être présent." }'

Réponse : {"cancelled": true}, ou {"alreadyCancelled": true} s'il était déjà annulé.

Voir Erreurs pour tous les codes d'erreur de ces endpoints et Limites de débit pour leurs limites.