Twitch Helix API — Chat

naftiko: 1.0.0-alpha2
info:
  label: Twitch Helix API — Chat
  description: 'Twitch Helix API — Chat. 10 operations. Lead operation: Twitch Send Chat Announcement. Self-contained Naftiko
    capability covering one Twitch business surface.'
  tags:
  - Twitch
  - Chat
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    TWITCH_API_KEY: TWITCH_API_KEY
capability:
  consumes:
  - type: http
    namespace: helix-chat
    baseUri: https://api.twitch.tv/helix
    description: Twitch Helix API — Chat business capability. Self-contained, no shared references.
    resources:
    - name: chat-announcements
      path: /chat/announcements
      operations:
      - name: sendchatannouncement
        method: POST
        description: Twitch Send Chat Announcement
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: broadcaster_id
          in: query
          type: string
          required: true
        - name: moderator_id
          in: query
          type: string
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: chat-badges
      path: /chat/badges
      operations:
      - name: getchannelchatbadges
        method: GET
        description: Twitch Get Channel Chat Badges
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: broadcaster_id
          in: query
          type: string
          required: true
    - name: chat-badges-global
      path: /chat/badges/global
      operations:
      - name: getglobalchatbadges
        method: GET
        description: Twitch Get Global Chat Badges
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: chat-chatters
      path: /chat/chatters
      operations:
      - name: getchatters
        method: GET
        description: Twitch Get Chatters
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: broadcaster_id
          in: query
          type: string
          required: true
        - name: moderator_id
          in: query
          type: string
          required: true
    - name: chat-emotes
      path: /chat/emotes
      operations:
      - name: getchannelemotes
        method: GET
        description: Twitch Get Channel Emotes
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: broadcaster_id
          in: query
          type: string
          required: true
    - name: chat-emotes-global
      path: /chat/emotes/global
      operations:
      - name: getglobalemotes
        method: GET
        description: Twitch Get Global Emotes
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: chat-emotes-set
      path: /chat/emotes/set
      operations:
      - name: getemotesets
        method: GET
        description: Twitch Get Emote Sets
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: emote_set_id
          in: query
          type: string
          required: true
    - name: chat-messages
      path: /chat/messages
      operations:
      - name: sendchatmessage
        method: POST
        description: Twitch Send Chat Message
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: chat-settings
      path: /chat/settings
      operations:
      - name: getchatsettings
        method: GET
        description: Twitch Get Chat Settings
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: broadcaster_id
          in: query
          type: string
          required: true
        - name: moderator_id
          in: query
          type: string
      - name: updatechatsettings
        method: PATCH
        description: Twitch Update Chat Settings
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: broadcaster_id
          in: query
          type: string
          required: true
        - name: moderator_id
          in: query
          type: string
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    authentication:
      type: bearer
      token: '{{env.TWITCH_API_KEY}}'
  exposes:
  - type: rest
    namespace: helix-chat-rest
    port: 8080
    description: REST adapter for Twitch Helix API — Chat. One Spectral-compliant resource per consumed operation, prefixed
      with /v1.
    resources:
    - path: /v1/chat/announcements
      name: chat-announcements
      description: REST surface for chat-announcements.
      operations:
      - method: POST
        name: sendchatannouncement
        description: Twitch Send Chat Announcement
        call: helix-chat.sendchatannouncement
        with:
          broadcaster_id: rest.broadcaster_id
          moderator_id: rest.moderator_id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/chat/badges
      name: chat-badges
      description: REST surface for chat-badges.
      operations:
      - method: GET
        name: getchannelchatbadges
        description: Twitch Get Channel Chat Badges
        call: helix-chat.getchannelchatbadges
        with:
          broadcaster_id: rest.broadcaster_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/chat/badges/global
      name: chat-badges-global
      description: REST surface for chat-badges-global.
      operations:
      - method: GET
        name: getglobalchatbadges
        description: Twitch Get Global Chat Badges
        call: helix-chat.getglobalchatbadges
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/chat/chatters
      name: chat-chatters
      description: REST surface for chat-chatters.
      operations:
      - method: GET
        name: getchatters
        description: Twitch Get Chatters
        call: helix-chat.getchatters
        with:
          broadcaster_id: rest.broadcaster_id
          moderator_id: rest.moderator_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/chat/emotes
      name: chat-emotes
      description: REST surface for chat-emotes.
      operations:
      - method: GET
        name: getchannelemotes
        description: Twitch Get Channel Emotes
        call: helix-chat.getchannelemotes
        with:
          broadcaster_id: rest.broadcaster_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/chat/emotes/global
      name: chat-emotes-global
      description: REST surface for chat-emotes-global.
      operations:
      - method: GET
        name: getglobalemotes
        description: Twitch Get Global Emotes
        call: helix-chat.getglobalemotes
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/chat/emotes/set
      name: chat-emotes-set
      description: REST surface for chat-emotes-set.
      operations:
      - method: GET
        name: getemotesets
        description: Twitch Get Emote Sets
        call: helix-chat.getemotesets
        with:
          emote_set_id: rest.emote_set_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/chat/messages
      name: chat-messages
      description: REST surface for chat-messages.
      operations:
      - method: POST
        name: sendchatmessage
        description: Twitch Send Chat Message
        call: helix-chat.sendchatmessage
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/chat/settings
      name: chat-settings
      description: REST surface for chat-settings.
      operations:
      - method: GET
        name: getchatsettings
        description: Twitch Get Chat Settings
        call: helix-chat.getchatsettings
        with:
          broadcaster_id: rest.broadcaster_id
          moderator_id: rest.moderator_id
        outputParameters:
        - type: object
          mapping: $.
      - method: PATCH
        name: updatechatsettings
        description: Twitch Update Chat Settings
        call: helix-chat.updatechatsettings
        with:
          broadcaster_id: rest.broadcaster_id
          moderator_id: rest.moderator_id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: helix-chat-mcp
    port: 9090
    transport: http
    description: MCP adapter for Twitch Helix API — Chat. One tool per consumed operation, routed inline through this capability's
      consumes block.
    tools:
    - name: twitch-send-chat-announcement
      description: Twitch Send Chat Announcement
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: helix-chat.sendchatannouncement
      with:
        broadcaster_id: tools.broadcaster_id
        moderator_id: tools.moderator_id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: twitch-get-channel-chat-badges
      description: Twitch Get Channel Chat Badges
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: helix-chat.getchannelchatbadges
      with:
        broadcaster_id: tools.broadcaster_id
      outputParameters:
      - type: object
        mapping: $.
    - name: twitch-get-global-chat-badges
      description: Twitch Get Global Chat Badges
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: helix-chat.getglobalchatbadges
      outputParameters:
      - type: object
        mapping: $.
    - name: twitch-get-chatters
      description: Twitch Get Chatters
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: helix-chat.getchatters
      with:
        broadcaster_id: tools.broadcaster_id
        moderator_id: tools.moderator_id
      outputParameters:
      - type: object
        mapping: $.
    - name: twitch-get-channel-emotes
      description: Twitch Get Channel Emotes
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: helix-chat.getchannelemotes
      with:
        broadcaster_id: tools.broadcaster_id
      outputParameters:
      - type: object
        mapping: $.
    - name: twitch-get-global-emotes
      description: Twitch Get Global Emotes
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: helix-chat.getglobalemotes
      outputParameters:
      - type: object
        mapping: $.
    - name: twitch-get-emote-sets
      description: Twitch Get Emote Sets
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: helix-chat.getemotesets
      with:
        emote_set_id: tools.emote_set_id
      outputParameters:
      - type: object
        mapping: $.
    - name: twitch-send-chat-message
      description: Twitch Send Chat Message
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: helix-chat.sendchatmessage
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: twitch-get-chat-settings
      description: Twitch Get Chat Settings
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: helix-chat.getchatsettings
      with:
        broadcaster_id: tools.broadcaster_id
        moderator_id: tools.moderator_id
      outputParameters:
      - type: object
        mapping: $.
    - name: twitch-update-chat-settings
      description: Twitch Update Chat Settings
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: helix-chat.updatechatsettings
      with:
        broadcaster_id: tools.broadcaster_id
        moderator_id: tools.moderator_id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.