POST /offers/message

Selects one eligible offer for a messaging surface and returns its link plus context fields so you can compose and send the message yourself. No message is composed server-side.

POST https://api.encorekit.com/encore/publisher/sdk/v1/offers/message

For when to call (thread triggers, per-thread caps) and how to compose and send the message, see the Automated Messaging guide. If you render offers in your own app UI rather than a text conversation, use POST /offers/feed: a nearly identical payload that returns an array and adds advertiserLogo, additionalImages, and a per-offer impressionUid.

Authentication

Pass your publishable key in the X-API-Key header (pk_live_* for production, pk_test_* for development). Multi-app projects also send X-Platform: api. Full model: overview’s Authentication section.

Request

Structure

interface MessageOfferRequest {
  clientId: string;              // required: stable per-operator identifier
  chatId: string;                // required: conversation/thread identifier
  attributes: {
    countryCode: string;         // required: ISO 3166-1 alpha-2, two uppercase letters
    language: string;            // required: BCP-47 language tag
    platform?: 'android' | 'ios' | 'web';  // recipient's device platform; never 'api'
  };
}

Field Reference

Field	Type	Required	Description
`clientId`	string	Yes	Stable per-operator identifier: the business, account, or operator your platform is sending on behalf of (for example a restaurant id). Carried through as an analytics dimension so impressions, clicks, and conversions can be broken down per client.
`chatId`	string	Yes	Conversation / thread identifier on the messaging platform. Used as the messaging-surface userId: it drives bandit seeding, the click-time transaction, and the userId dimension on the click event.
`attributes.countryCode`	string	Yes	ISO 3166-1 alpha-2, two uppercase letters (for example `"US"`, `"GB"`, `"CA"`). Drives geo-targeting and the country dimension on analytics.
`attributes.language`	string	Yes	BCP-47 language tag (for example `"en"`, `"es"`). Drives creative locale resolution.
`attributes.platform`	string	No	The recipient’s device platform: `"android"`, `"ios"`, or `"web"`. Drives creative compatibility filtering. Optional for API-platform apps: omit it to receive any eligible offer untrimmed. Never send `"api"` here.

Response

Structure

interface MessageOfferResponse {
  success: true;
  offer: {
    clickUrl: string;              // branded short link on link.encorekit.com
    title: string;                 // offer headline
    description: string | null;    // short supporting line
    imageUrl: string;              // primary creative image URL
    advertiserName: string;        // advertiser / brand name
    perk?: string | null;          // campaign value proposition
    badgeLabel: 'free_trial' | 'discount' | null;  // constrained promo badge
  } | null;                        // null when no eligible offer was found
}

Field Reference

Field	Type	Description
`success`	`true`	Always `true` on a 200. Non-success outcomes come back as 4xx/5xx; see Status codes.
`offer`	object \| `null`	`null` when no eligible offer was found for this user (geo-targeted out, no active campaigns, all creatives filtered by platform). Never a 404: skip the promo step and send only your client’s normal reply.
`offer.clickUrl`	URL	Branded short link on the fixed host `link.encorekit.com`. A plain URL: embed it as text in your message; it tracks the click and redirects to the advertiser’s landing page. End-user-visible. Always include it in the message you send.
`offer.title`	string	Headline of the offer. Use as the lead line when composing your message.
`offer.description`	string \| `null`	Short supporting line about the offer (for example `"Songs & Podcasts"`). May be `null`.
`offer.imageUrl`	URL	Creative image. Attach it as a media message if your channel supports media; otherwise omit it.
`offer.advertiserName`	string	The advertiser / brand name (for example `"Apple Music"`).
`offer.perk`	string \| `null`	The campaign value proposition (for example `"6 months free"`), or `null`. May also be absent from the object.
`offer.badgeLabel`	`"free_trial"` \| `"discount"` \| `null`	Constrained promo badge, distinct from `perk`. Always present (`null` when the campaign has none). Map the enum to your own display text.

The response carries no internal identifiers (impression, campaign, creative, or request ids) and no server-composed message; you build the text from the fields above.

Example

curl --location --request POST 'https://api.encorekit.com/encore/publisher/sdk/v1/offers/message' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "clientId": "client-42",
    "chatId": "8b3f7c10-9d4e-4d2a-91a1-3f0e8a1c0b5d",
    "attributes": {
      "countryCode": "US",
      "language": "en",
      "platform": "ios"
    }
  }'

{
  "success": true,
  "offer": {
    "clickUrl": "https://link.encorekit.com/aB3xY7q2",
    "title": "Free Apple Music for 6 months",
    "description": "Songs & Podcasts",
    "imageUrl": "https://storage.googleapis.com/encore-assets-prod/creatives/2c643fc5-91cb-4b0a-ba0a-0536c2c4f871/primary-1778695603093.png",
    "advertiserName": "Apple Music",
    "perk": "6 months free",
    "badgeLabel": "free_trial"
  }
}

Status codes

Code	Meaning
`200`	Success. `offer` may be `null` if no eligible offer.
`400`	Malformed request (missing required field, invalid `attributes.countryCode`). Don’t retry; fix the request.
`401`	Missing or invalid `X-API-Key`.
`409`	Your client has exceeded their trial limit (rare).
`429`	Rate-limited. Back off and retry.
`503`	Server temporarily over capacity. Retry with backoff.
`5xx` (other)	Encore-side failure. Proceed without the promo message.

Retry guidance

Idempotency is on your side. The server does not deduplicate retries; every call generates a fresh short link and analytics row. Call /offers/message once per inbound message you’ve decided to attach an offer to, and de-dupe inbound webhooks on your side before calling.
Use exponential backoff with jitter (for example 200ms, 1s, 5s, max 3 retries) for transient failures (429 / 503 / network).
After exhausting retries, drop the call and send only your client’s normal reply.

Automated Messaging guide: triggers, caps, and message composition.
POST /offers/feed: the in-app sibling that returns a ranked array with per-offer impression handles.
API Reference overview: auth and the claim model.

​Authentication

​Request

​Structure

​Field Reference

​Response

​Structure

​Field Reference

​Example

​Status codes

​Retry guidance

​Related

Authentication

Request

Structure

Field Reference

Response

Structure

Field Reference

Example

Status codes

Retry guidance

Related