alori

Développeurs

Messages avec boutons dans le Team chat

Publie un message avec des boutons, des menus, des sélecteurs de date et des formulaires dans un canal du Team chat. Quand quelqu'un clique, Alori envoie le clic à ton adresse, et ta réponse met le message à jour. Les messages utilisent le Block Kit de Slack, donc du code écrit pour Slack demande deux changements : l'adresse et la signature.

Deux façons de publier

Avec ta clé d'API
POST /v1/chat/messages avec une clé Accès complet, un channel (son identifiant ou son nom), des blocks et une interaction_url. Le message s'affiche sous le nom de ta clé avec un badge App, et ses clics sont signés avec le SHA-256 en hexadécimal de ta clé d'API. Prends cette façon si ton logiciel appelle déjà l'API.
Avec le lien d'un canal
Pas besoin de clé. Dans le Team chat, ouvre le canal, puis Options du canal › Recevoir des messages d'autres apps › Créer un lien, et envoie le même JSON en POST à ce lien, sans channel. Le message s'affiche sous le nom du lien, et ses clics sont signés avec le jeton à la fin du lien. Quiconque a le lien peut publier, alors garde-le secret.

Prendre un lead, étape par étape

Un nouveau lead arrive dans #leads avec un bouton Prendre. La première personne qui appuie l'obtient, et la carte l'indique à tout le monde.

1. Publie la carte

curl -X POST https://api.alori.dev/v1/chat/messages \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "leads",
    "text": "New lead: Jane Doe, Doe Rénovations",
    "interaction_url": "https://example.com/alori/clicks",
    "blocks": [
      {
        "type": "section",
        "text": {
          "type": "mrkdwn",
          "text": "New lead from Meta ads: *Jane Doe*"
        }
      },
      {
        "type": "section",
        "fields": [
          {
            "type": "mrkdwn",
            "text": "*Phone*\n+1 514 555 0199"
          },
          {
            "type": "mrkdwn",
            "text": "*Email*\njane.doe@example.com"
          },
          {
            "type": "mrkdwn",
            "text": "*Company*\nDoe Rénovations"
          }
        ]
      },
      {
        "type": "actions",
        "block_id": "lead",
        "elements": [
          {
            "type": "button",
            "action_id": "claim",
            "text": {
              "type": "plain_text",
              "text": "Claim lead"
            },
            "style": "primary",
            "value": "lead_8812"
          },
          {
            "type": "button",
            "action_id": "open",
            "text": {
              "type": "plain_text",
              "text": "Open deal"
            },
            "url": "https://example.com/leads/8812"
          }
        ]
      }
    ]
  }'

Alori répond avec l'identifiant du message et celui de son canal.

{
  "ok": true,
  "messageId": "m12ghi7k3p",
  "channelId": "j97def4a21"
}
La carte dans le Team chat : le premier qui appuie sur Prendre le lead l'obtient.
La carte dans le Team chat : le premier qui appuie sur Prendre le lead l'obtient.

2. Ton interaction_url reçoit le clic

Un POST avec un seul champ de formulaire, payload, qui contient ce JSON (le block_actions de Slack). actions[0].value est la valeur que tu as donnée au bouton. Réponds par un 2xx en moins de 3 secondes.

{
  "type": "block_actions",
  "user": {
    "id": "k57abc2m9q",
    "name": "Alex Martin",
    "username": "Alex Martin",
    "email": "alex@example.com"
  },
  "channel": {
    "id": "j97def4a21",
    "name": "leads"
  },
  "container": {
    "type": "message",
    "message_ts": "m12ghi7k3p",
    "channel_id": "j97def4a21",
    "is_ephemeral": false
  },
  "message": {
    "ts": "m12ghi7k3p",
    "text": "New lead: Jane Doe, Doe Rénovations",
    "blocks": [
      "…"
    ]
  },
  "actions": [
    {
      "type": "button",
      "action_id": "claim",
      "block_id": "lead",
      "value": "lead_8812",
      "action_ts": "1792580000.123"
    }
  ],
  "state": {
    "values": {
      "lead": {
        "claim": {
          "type": "button",
          "value": "lead_8812"
        }
      }
    }
  },
  "response_url": "https://api.alori.dev/v1/chat/responses/<appId>/<one-time token>",
  "trigger_id": "8f2c0e…"
}

3. Réponds pour le marquer pris

Envoie ceci comme corps du 2xx, ou en POST à response_url. replace_original change la carte pour tout le monde dans le canal.

{
  "replace_original": true,
  "text": "Jane Doe was claimed by Alex Martin",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "New lead from Meta ads: *Jane Doe*"
      }
    },
    {
      "type": "context",
      "elements": [
        {
          "type": "mrkdwn",
          "text": "✅ Claimed by Alex Martin"
        }
      ]
    }
  ]
}
Après ta réponse avec replace_original : le bouton disparaît et tout le monde voit qui l'a.
Après ta réponse avec replace_original : le bouton disparaît et tout le monde voit qui l'a.

Vérifie la signature

Chaque clic et chaque formulaire envoyé à interaction_url porte X-Alori-Request-Timestamp (secondes Unix) et X-Alori-Signature: v0=<hex>, le HMAC-SHA256 de v0:<timestamp>:<corps brut>. La clé dépend de la façon dont le message a été publié : le SHA-256 en hexadécimal de ta clé d'API pour le point d'accès, le jeton à la fin du lien pour le lien d'un canal. Refuse tout ce qui a plus de 5 minutes.

# Headers: X-Alori-Signature: v0=5f0c…   X-Alori-Request-Timestamp: 1792580000
# Posted with the API: the key is the SHA-256 hex of your API key.
SIGNING_KEY=$(printf %s "$ALORI_API_KEY" | openssl dgst -sha256 | sed "s/^.* //")
# Posted with a channel's link: the key is the token at the end of the link.
# SIGNING_KEY="$ALORI_CHAT_TOKEN"
printf 'v0:%s:%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SIGNING_KEY"

La même carte avec le lien d'un canal

Le lien prend aussi les webhooks de Slack et de Discord tels quels, et répond { ok, ts }, où ts est l'identifiant du message. Ces appels marchent sur les messages du lien :

curl -X POST "https://api.alori.dev/v1/chat/hooks/<appId>/<token>" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "New lead: Jane Doe, Doe Rénovations",
    "interaction_url": "https://example.com/alori/clicks",
    "blocks": [
      {
        "type": "section",
        "text": {
          "type": "mrkdwn",
          "text": "New lead from Meta ads: *Jane Doe*"
        }
      },
      {
        "type": "section",
        "fields": [
          {
            "type": "mrkdwn",
            "text": "*Phone*\n+1 514 555 0199"
          },
          {
            "type": "mrkdwn",
            "text": "*Email*\njane.doe@example.com"
          },
          {
            "type": "mrkdwn",
            "text": "*Company*\nDoe Rénovations"
          }
        ]
      },
      {
        "type": "actions",
        "block_id": "lead",
        "elements": [
          {
            "type": "button",
            "action_id": "claim",
            "text": {
              "type": "plain_text",
              "text": "Claim lead"
            },
            "style": "primary",
            "value": "lead_8812"
          },
          {
            "type": "button",
            "action_id": "open",
            "text": {
              "type": "plain_text",
              "text": "Open deal"
            },
            "url": "https://example.com/leads/8812"
          }
        ]
      }
    ]
  }'

Appels sur le lien

POST https://api.alori.dev/v1/chat/hooks/<appId>/<token>/update     { "ts": "m12ghi7k3p", "text": "…", "blocks": [ … ] }
POST https://api.alori.dev/v1/chat/hooks/<appId>/<token>/delete     { "ts": "m12ghi7k3p" }
POST https://api.alori.dev/v1/chat/hooks/<appId>/<token>/ephemeral  { "user": "alex@example.com", "text": "Only you see this" }
POST https://api.alori.dev/v1/chat/hooks/<appId>/<token>/views.open { "trigger_id": "8f2c0e…", "view": { … } }

Blocs et contrôles

Ce que le Team chat affiche. Le reste dans blocks est laissé de côté, et les limites de Slack s'appliquent.

Bloc ou contrôleCe qu'il fait
sectionDu texte en mrkdwn de Slack, jusqu'à 10 fields côte à côte, et un contrôle ou une image à droite (accessory).
actionsUne rangée de 25 contrôles au plus.
contextDu petit texte gris et des images.
header, divider, imageUn titre, une ligne, une image.
buttonstyle primary ou danger, et une fenêtre confirm au besoin. Un bouton avec seulement une url ouvre cette page et n'envoie pas de clic.
static_select, multi_static_select, overflowUn menu de tes options, un menu à choix multiples, ou le menu ….
users_select, channels_select, conversations_selectChoisir des coéquipiers ou un canal. Le clic donne leurs identifiants Alori.
datepicker, timepickerUne date en AAAA-MM-JJ, une heure en HH:MM.
checkboxes, radio_buttonsJusqu'à 10 choix.

Répondre plus tard avec response_url

Chaque clic arrive avec un response_url. Envoie-lui en POST les mêmes réponses que le corps du 2xx, pendant 30 minutes et jusqu'à 5 fois : replace_original, delete_original, ou un nouveau message avec text et blocks.

curl -X POST "https://api.alori.dev/v1/chat/responses/<appId>/<one-time token>" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Someone claimed this lead a moment before you.",
    "response_type": "ephemeral"
  }'

Messages privés

Un nouveau message dans une réponse ne va qu'à la personne qui a cliqué, sauf si response_type vaut in_channel; thread_ts le met dans un fil. Le lien d'un canal peut aussi envoyer un message privé n'importe quand avec /ephemeral. Les messages privés disparaissent après 24 heures.

Modifier ou supprimer

Avec le point d'accès, change ou retire un message dans la réponse à un clic, avec replace_original ou delete_original. Avec le lien d'un canal, /update et /delete marchent en tout temps sur les messages du lien. Tes coéquipiers ne peuvent pas modifier le message d'une app.

Formulaires

Le lien d'un canal peut ouvrir un formulaire pour la personne qui a cliqué : envoie en POST /views.open avec le trigger_id du clic, en moins de 3 secondes, et une vue modal. Quand elle appuie sur Enregistrer, interaction_url reçoit un view_submission avec ce qu'elle a entré, signé comme un clic. Réponds avec response_action : errors garde le formulaire ouvert avec une ligne sous chaque champ nommé, update le remplace, et clear ou un 2xx vide le ferme.

Un formulaire ouvert d'un bouton avec views.open : ton app reçoit les réponses en view_submission.
Un formulaire ouvert d'un bouton avec views.open : ton app reçoit les réponses en view_submission.

Ouvrir un formulaire

{
  "trigger_id": "8f2c0e…",
  "view": {
    "type": "modal",
    "callback_id": "lost_reason",
    "title": {
      "type": "plain_text",
      "text": "Why was it lost?"
    },
    "submit": {
      "type": "plain_text",
      "text": "Save"
    },
    "blocks": [
      {
        "type": "input",
        "block_id": "reason",
        "label": {
          "type": "plain_text",
          "text": "Reason"
        },
        "element": {
          "type": "static_select",
          "action_id": "pick",
          "options": [
            {
              "text": {
                "type": "plain_text",
                "text": "Price"
              },
              "value": "price"
            },
            {
              "text": {
                "type": "plain_text",
                "text": "Timing"
              },
              "value": "timing"
            }
          ]
        }
      },
      {
        "type": "input",
        "block_id": "note",
        "optional": true,
        "label": {
          "type": "plain_text",
          "text": "Note"
        },
        "element": {
          "type": "plain_text_input",
          "action_id": "text",
          "multiline": true
        }
      }
    ]
  }
}

Ce que reçoit interaction_url

{
  "type": "view_submission",
  "user": {
    "id": "k57abc2m9q",
    "name": "Alex Martin"
  },
  "view": {
    "id": "v41xyz…",
    "callback_id": "lost_reason",
    "state": {
      "values": {
        "reason": {
          "pick": {
            "type": "static_select",
            "selected_option": {
              "value": "price"
            }
          }
        },
        "note": {
          "text": {
            "type": "plain_text_input",
            "value": "Went with a cheaper quote"
          }
        }
      }
    }
  }
}

Afficher une erreur sous un champ

{
  "response_action": "errors",
  "errors": {
    "note": "Tell us which competitor, please."
  }
}

Limites

  • 50 blocs par message, et 200 Ko de blocs par le point d'accès.
  • interaction_url : https, 2 000 caractères au plus.
  • Réponds à un clic en moins de 3 secondes. Un response_url marche pendant 30 minutes et pour 5 réponses, un trigger_id une seule fois, en moins de 3 secondes.
  • Le lien d'un canal publie jusqu'à 60 messages par minute. Le point d'accès compte dans les 120 requêtes par minute de ta clé.
  • Les action_id qui commencent par alori. sont réservés aux boutons d'Alori, comme Prendre le lead sur les nouveaux leads, et sont refusés.

Retour à la doc de l'API