@keystrokehq/giphy

Keystroke integration for Giphy — GIF, sticker, emoji, channel, and tag search primitives for workflows that react to events with an on-brand animated response or embed Giphy-hosted media in outbound messages.

This integration is API-key authenticated. Giphy has no OAuth flow and no webhook platform.

Install

pnpm add @keystrokehq/giphy

Package exports

Import from the canonical barrel subpaths:

• @keystrokehq/giphy — credential sets, operations, and schemas
• @keystrokehq/giphy/credential-sets — giphyCredentialSet and GiphyCredentials
• @keystrokehq/giphy/operations — all 27 Giphy operations (+ *Tool aliases)
• @keystrokehq/giphy/schemas — shared Zod schemas and inferred types

Operations (27)

| Domain | Operation id | Docs endpoint | | ---------- | ------------------------- | ----------------------------------------------------------------------------- | | gifs | giphy.search-gifs | GET /v1/gifs/search | | gifs | giphy.trending-gifs | GET /v1/gifs/trending | | gifs | giphy.translate-gif | GET /v1/gifs/translate | | gifs | giphy.random-gif | GET /v1/gifs/random | | gifs | giphy.get-gif-by-id | GET /v1/gifs/{gif_id} | | gifs | giphy.get-gifs-by-ids | GET /v1/gifs?ids=… (up to 100) | | stickers | giphy.search-stickers | GET /v1/stickers/search | | stickers | giphy.trending-stickers | GET /v1/stickers/trending | | stickers | giphy.translate-sticker | GET /v1/stickers/translate | | stickers | giphy.random-sticker | GET /v1/stickers/random | | stickers | giphy.get-sticker-by-id | GET /v1/stickers/{sticker_id} | | stickers | giphy.get-stickers-by-ids | GET /v1/stickers?ids=… | | emoji | giphy.list-emoji | GET /v2/emoji | | emoji | giphy.get-emoji-variations | GET /v2/emoji/{gif_id}/variations | | channels | giphy.search-channels | GET /v1/channels/search | | channels | giphy.get-channel | GET /v1/channels/{id} | | channels | giphy.get-channel-content | GET /v1/channels/{id}/content | | channels | giphy.get-channel-subchannels | GET /v1/channels/{id}/children | | tags | giphy.random-tag | GET /v1/randomtag | | tags | giphy.tag-search | GET /v1/gifs/search/tags?q=… (Autocomplete) | | tags | giphy.trending-tags | GET /v1/trending/searches | | tags | giphy.related-tags | GET /v1/tags/related/?term=… | | categories | giphy.list-categories | GET /v1/gifs/categories | | categories | giphy.get-category | GET /v1/gifs/categories/{category} | | categories | giphy.get-category-gifs | GET /v1/gifs/categories/{category}/{subcategory} | | uploads | giphy.upload-gif | POST upload.giphy.com/v1/gifs — gated, see Upload gating | | analytics | giphy.action-register | GET giphy-analytics.giphy.com/v2/pingback_simple?… — see Analytics |

API key setup

Giphy offers three key tiers, in order of capability:

1. Beta / developer key — self-serve at https://developers.giphy.com. Rate-limited to approximately 42 requests/hour, 1000 requests/day. Read-only coverage of search, trending, translate, random, by-id, emoji, tags, and channels. Upload endpoints return 401/403.
2. Production key — granted after Giphy's manual "production" review. Higher rate limits, same read surface as beta.
3. Business / SDK partner key — direct agreement with Giphy. Unlocks upload and commercial routing.

All tiers authenticate via a single query parameter (?api_key=<your-key>). Store the key in Keystroke's credential vault under the logical key GIPHY_API_KEY.

import { giphyCredentialSet } from '@keystrokehq/giphy/credential-sets';

// giphyCredentialSet.auth is the Zod schema that resolved credentials must satisfy.
// The field required at runtime is `GIPHY_API_KEY`.

Default content rating

Every search / trending / translate / random endpoint accepts a rating parameter. Operations pass through an optional rating input; when omitted, the HTTP client defaults to 'g' (general audiences) on endpoints that support it.

Override per operation when the flow's audience is different.

Note: giphy.get-gif-by-id and giphy.get-gifs-by-ids accept an optional rating filter. The client intentionally does not inject a default rating on these endpoints.

Error handling

Giphy API failures surface as GiphyApiError with a stable kind discriminator. See operation run handlers and the client in src/utils/client.ts for the full error taxonomy.

Attribution: Giphy requires a visible "Powered by Giphy" mark anywhere Giphy media is displayed. This is a surface-side obligation for the flow author, not something the package enforces at runtime.

Quickstart

import { giphyCredentialSet } from '@keystrokehq/giphy/credential-sets';
import { searchGifsOperation } from '@keystrokehq/giphy/operations';

void giphyCredentialSet.id;
void searchGifsOperation.id;

Analytics pingback

import { actionRegisterOperation } from '@keystrokehq/giphy/operations';

actionRegisterOperation.input.parse({
  pingback_url:
    'https://giphy-analytics.giphy.com/v2/pingback_simple?analytics_response_payload=eZm9v&action_type=SEEN',
  random_id: 'per-user-random-id',
});

Upload gating

giphy.upload-gif targets https://upload.giphy.com/v1/gifs. Beta and standard production keys are typically not upload-capable. The operation declares needsApproval: true so hosts can gate it behind an explicit approval step.

No webhooks

Giphy does not emit webhook events. If you need an "event-like" flow, use the core polling scheduler with giphy.trending-gifs or giphy.get-channel-content.