Dialogflow Integration

Serve ads from a Dialogflow-based chatbot by calling the Advertising.chat fetch API from your fulfillment webhook. The fetch API renders ads in a Dialogflow-native format (format=dialogflow), so the result can be added directly to your intent's fulfillment messages.

Note

Earlier versions of this integration pointed Dialogflow at a hosted webhook (webhooks.advertising.chat) configured with direqt-* headers. That endpoint has been retired. Integrate by calling the fetch API from your own fulfillment webhook as described below.

How it works

1. Dialogflow invokes your fulfillment webhook for an intent.
2. Your webhook calls the Advertising.chat fetch API, identifying the ad unit (placement) to fill.
3. The fetch API returns the winning ad rendered as a Dialogflow Card message.
4. Your webhook appends the card to the intent's fulfillment messages — typically after your own response, so the user's conversation flow is the same whether or not an offer is served.

Calling the fetch API

POST https://ads.advertising.chat/v1/fetch/v2
     ?key=<your API key>
     &adUnit=<ad unit code>
     &format=dialogflow
     &subscriber=<opaque user id>

Parameter	Description
key	Your API key, from the Advertising.chat Console. May also be passed as apiKey, or as an Authorization: Bearer <key> header.
adUnit	The code of the ad unit (placement) to fill. If omitted, the default ad unit for your org is used. (The enterprise Offer Manager calls an ad unit a Moment; the moment parameter is a deprecated alias — see the glossary.)
format	Use dialogflow to receive a Dialogflow card rendering.
subscriber	Optional. An opaque identifier for the current user, used for frequency capping and reporting.
.<attr>	Optional. Targeting attributes, passed as query parameters with a leading dot (e.g. .FirstName=Omar), or as an attributes JSON object in the request body.

A successful response contains the rendered ad in payload, plus a messageId identifying the fetch (the fetch id — pass it as fetchEventId when reporting events):

{
  "payload": {
    "card": {
      "title": "...",
      "subtitle": "...",
      "imageUri": "https://...",
      "buttons": [{ "text": "...", "postback": "https://..." }]
    }
  },
  "messageId": "direqt-<fetch id>"
}

Example webhook code

const axios = require('axios');

async function fetchAd(adUnit, subscriber) {
  const response = await axios.post(
    'https://ads.advertising.chat/v1/fetch/v2',
    {},
    {
      params: {
        key: process.env.ADCHAT_API_KEY,
        adUnit,
        format: 'dialogflow',
        subscriber,
      },
    }
  );
  return response.data.payload; // e.g. { card: { ... } }
}

Add the returned card to your webhook's fulfillmentMessages after your own response messages.

Choosing an ad unit for an intent

A useful convention is to use the intent's action value as the ad unit code. For example, the Default Welcome Intent has an action value of input.welcome; create an ad unit with the code input.welcome in the Advertising.chat Console and pass that value as the adUnit parameter when your webhook handles the intent. This gives you per-intent control over which ads are eligible, using the same targeting rules (Offer Manager Rules) you use everywhere else.

Test it out

Use the "Try it now" function in the Dialogflow console to invoke an intent handled by your webhook. When your integration is successful, you'll see the offer delivered after the intent's own response.