Guida rapida

Questa guida spiega come registrarsi e ricevere eventi utilizzando gli endpoint dell’API X Activity. In generale, il processo prevede 3 passaggi:

1. Identificare l’id utente dell’utente di cui si desidera filtrare gli eventi
2. Creare una sottoscrizione per il tipo di evento che si desidera filtrare per quell’utente
3. Ricevere gli eventi utilizzando un webhook o una connessione HTTP persistente (stream)

​

Recuperare gli ID utente

Prima di creare le sottoscrizioni, devi conoscere l’ID utente dell’account su cui vuoi applicare il filtro. In questo esempio useremo l’handle XDevelopers. Puoi ottenere gli ID utente in vari modi, tra cui:

Cerca l’ID di un utente dal nome utente:

curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" "https://api.x.com/2/users/by/username/xdevelopers"

Recupera il tuo id utente:

curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" https://api.x.com/2/users/me

Entrambi gli endpoint restituiscono informazioni sull’utente, incluso il campo id, che puoi utilizzare nei filtri di sottoscrizione. Di seguito è riportato un esempio di risposta JSON:

{
    "data": {
        "id": "2244994945",
        "name": "Developers",
        "username": "XDevelopers"
    }
}

​

Creazione di una sottoscrizione

Il passo successivo è creare una sottoscrizione. In questo esempio, ci iscriveremo agli aggiornamenti della biografia di XDevelopers. Per farlo, includeremo user_id e event_type nel body JSON. In questo caso, event_type è ProfileBioUpdate.

Indicheremo l’ID utente di X Developer: 2244994945, e un tag opzionale:

{
  "event_type": "ProfileBioUpdate",
  "filter": {
    "user_id": "2244994945"
  },
  "tag": "aggiornamenti della bio di X Developers"
}

Useremo il nostro Bearer Token (dal portale sviluppatori) per l’autenticazione su tutti gli endpoint relativi a XAA:

curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  https://api.x.com/2/activity/subscriptions \
  -X POST \
  -d '{
    "event_type": "ProfileBioUpdate",
    "filter": {
      "user_id": "2244994945"
    },
    "tag": "aggiornamenti della bio degli Xdevelopers"
  }'

Al buon esito della richiesta, il tuo abbonamento verrà creato:

{
  "data":[
    {
      "created_at":"2025-10-09T16:35:08.000Z",
      "event_type":"ProfileBioUpdate",
      "filter":{
        "user_id":"2244994945"
      },
      "subscription_id":"1976325569252868096",
      "tag": "aggiornamenti della bio di X Developers"
      "updated_at":"2025-10-09T16:35:08.000Z"
    }
  ],
  "meta": {
    "total_subscriptions": 1
  }
}

​

Recupero degli eventi

Una volta creata la sottoscrizione, possiamo ricevere gli eventi tramite webhook o un flusso HTTP persistente. In questo esempio, apriremo il flusso HTTP persistente:

curl -H "Authorization: Bearer IL_TUO_BEARER_TOKEN" https://api.x.com/2/activity/stream

Quando l’account Xdevelopers aggiorna la bio del profilo, l’evento viene recapitato tramite lo stream:

{
  "data": {
    "filter": {
      "user_id": "2244994945"
    },
    "event_type": "ProfileBioUpdate",
    "tag": "Aggiornamenti della bio di Xdevelopers",
    "payload": {
      "before": "Mars & Cars",
      "after": "Mars, Cars & AI"
    }
  }
}

​

Gestione degli abbonamenti

L’API X Activity fornisce endpoint per gestire i tuoi abbonamenti tramite le operazioni CRUD standard.

​

Crea abbonamento

Crea un nuovo abbonamento per ricevere eventi:

curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -X POST \
  https://api.x.com/2/activity/subscriptions \
  -d '{
    "event_type": "ProfileBioUpdate",
    "filter": {
      "user_id": "123456789"
    },
    "tag": "i miei aggiornamenti della bio",
    "webhook_id": "1976325569252868099"
  }'

Nota:

• Il campo tag è facoltativo. Può essere usato per identificare gli eventi al momento della consegna.
• Anche il campo webhook_id è facoltativo. Consulta la nostra documentazione sui webhook per assistenza nella configurazione di un webhook. Se viene specificato un webhook_id, l’evento sarà recapitato al webhook indicato, oltre che allo stream, se aperto.

Risposta:

{
  "data": {
    "subscription_id": "1976325569252868096",
    "event_type": "ProfileBioUpdate",
    "filter": {
      "user_id": "123456789"
    },
    "created_at": "2025-10-09T16:35:08.000Z",
    "updated_at": "2025-10-09T16:35:08.000Z",
    "tag": "i miei aggiornamenti sulla bio",
    "webhook_id": "1976325569252868099"
  }
}

​

Elenco abbonamenti

Recupera tutti gli abbonamenti attivi per la tua applicazione:

curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  https://api.x.com/2/activity/subscriptions

Risposta:

{
  "data": [
    {
      "subscription_id": "1976325569252868096",
      "event_type": "ProfileBioUpdate",
      "filter": {
        "user_id": "123456789"
      },
      "created_at": "2025-10-09T16:35:08.000Z",
      "updated_at": "2025-10-10T03:50:59.000Z",
    },
    {
      "subscription_id": "1976325569252868097",
      "event_type": "ProfilePictureUpdate",
      "filter": {
        "user_id": "987654321"
      },
      "created_at": "2025-10-08T14:35:08.000Z",
      "updated_at": "2025-10-08T14:35:08.000Z",
    }
  ],
  "meta": {
    "total_subscriptions": 2
  }
}

​

Elimina abbonamento

Rimuovere un abbonamento:

curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -X DELETE \
  https://api.x.com/2/activity/subscriptions/1976325569252868096

Risposta:

{
  "data": {
    "deleted": true
  },
  "meta": {
    "total_subscriptions": 0
  }
}

total_subscriptions indica il numero di abbonamenti ancora associati alla tua app dopo l’operazione di eliminazione.

​

Aggiornare la sottoscrizione

L’endpoint PUT consente di aggiornare il metodo di recapito o il tag di una sottoscrizione.

Aggiornare filter o event_type richiede l’eliminazione della sottoscrizione esistente e la creazione di una nuova.

curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -X PUT \
  https://api.x.com/2/activity/subscriptions/1976325569252868096 \
  -d '{
    "tag": "my new tag",
    "webhook_id": "192846273860294839"
  }'

Risposta:

{
  "data": {
    "subscription_id": "1976325569252868096",
    "event_type": "ProfileBioUpdate",
    "filter": {
      "user_id": "123456789"
    },
    "created_at": "2025-10-09T16:35:08.000Z",
    "updated_at": "2025-10-10T17:10:58.000Z",
    "tag": "il mio nuovo tag",
    "webhook_id": "192846273860294839"
  },
  "meta": {
    "total_subscriptions": 1
  }
}