WeChat全シミュレーション連携 - Udesk

基本情報

Udeskが提供する独自のWeChat公式アカウント連携ソリューションでは、UdeskがWeChat公式アカウントの権限を取得するのではなく、ミドルウェアを作成してWeChat公式アカウントの権限を取得し、カスタマーサポートシナリオに合ったメッセージとイベントをUdeskに転送します。

ミドルウェアの開発者は、以下の状況を処理する必要があります。

1. WeChatサーバーからのメッセージを受信し、それをUDESKシステムに転送し、UDESKシステムからの応答をWeChatサーバーに渡す
2. UDESKシステムからのリクエストを受信し、それをWeChatサーバーに転送し、WeChatサーバーからの応答をUDESKシステムに渡す
  + POSTリクエストを受け取り、クエリパラメータがない場合、メッセージのプッシュと見なす
  + POSTリクエストを受け取り、type=TYPEのクエリパラメータがある場合、マルチメディアメッセージのアップロード（一時素材の追加）と見なす
  + GETリクエストを受け取り、media_id=MEDIA_IDのクエリパラメータがある場合、マルチメディアメッセージの取得（一時素材の取得）と見なす
  + GETリクエストを受け取り、openid=OPEN_IDのクエリパラメータがある場合、ユーザー基本情報の取得と見なす

注意 UDESKシステムがシミュレーションミドルウェアにメッセージをプッシュする際、appidは含まれません。顧客が複数の公式アカウントを連携している場合は、シミュレーションドメインを以下の形式に設定することをお勧めします。

1. http://udesk.simulate_weixin.com/APPID
2. http://udesk.simulate_weixin.com?appid=APPID

1. メッセージ受信

WeChatサーバーがシミュレーションミドルウェアにメッセージを送信した後、シミュレーションミドルウェアはWeChatから送信されたメッセージをUDESKシステムに透過的に転送し、UDESKシステムからの応答をWeChatサーバーに渡します。

リクエスト仕様

発信元	受信先	リクエスト方法
シミュレーションミドルウェア	UDESKシステム	POST

POST 'UDESKが提供するURL'

注 URLの確認場所：【管理センター-チャネル管理-WeChat-管理】内の「URL」

リクエストパラメータ

このリクエストパラメータは WeChat開発者ドキュメント-メッセージ管理-通常メッセージの受信と一致している必要があります

戻り値

UDESKシステムからの応答には2つのケースがあり、どちらのケースでも、シミュレーションミドルウェアはその応答を直接WeChatサーバーに透過的に渡すことができます
1. 空の文字列、 ""
2. 特定のXML構造の情報。詳細は WeChat開発者ドキュメント-ユーザーメッセージへの受動的返信を参照してください

例

# 呼び出し例
curl udesk.udesk.com/weixin/olloowpoeakkskknx0ijm -d '{
<xml>
  <ToUserName><![CDATA[toUser]]></ToUserName>
  <FromUserName><![CDATA[fromUser]]></FromUserName>
  <CreateTime>1348831860</CreateTime>
  <MsgType><![CDATA[text]]></MsgType>
  <Content><![CDATA[this is a test]]></Content>
  <MsgId>1234567890123456</MsgId>
</xml>
}'

<!-- 応答例 -->
<xml>
  <ToUserName><![CDATA[toUser]]></ToUserName>
  <FromUserName><![CDATA[fromUser]]></FromUserName>
  <CreateTime>12345678</CreateTime>
  <MsgType><![CDATA[text]]></MsgType>
  <Content><![CDATA[こんにちは]]></Content>
</xml>

2. メッセージのプッシュ

UDESKシステムがシミュレーションミドルウェアにメッセージをプッシュし、シミュレーションミドルウェアはWeChatサーバーの客服消息-发消息インターフェースをリクエストし、WeChatサーバーからの戻り値をUDESKシステムに転送します。

シミュレーションミドルウェアは、リクエストボディの内容をJSON形式に変換してからWeChatサーバーに送信する必要があります。
シミュレーションミドルウェアがWeChatサーバーにメッセージをプッシュする方法の詳細は、WeChat開発者ドキュメント-カスタマーサービスメッセージ-カスタマーサービスインターフェース.メッセージ送信をご覧ください。

発信元	受信先	リクエスト方法
UDESKシステム	シミュレーションミドルウェア	POST

リクエスト説明

POST '顧客が入力したシミュレーションドメインアドレス'

注：シミュレーションドメインの設定場所：【管理センター-チャネル管理-WeChat-管理】内の「シミュレーションドメイン」

リクエストパラメータ

テキストメッセージの送信

パラメータ	説明
touser	顧客のopenid
msgtype	メッセージタイプ、ここでは'text'
text[content]	メッセージ内容

画像メッセージの送信

パラメータ	説明
touser	顧客のopenid
msgtype	メッセージタイプ、ここでは'image'
image[media_id]	マルチメディアメッセージID

音声メッセージの送信

パラメータ	説明
touser	顧客のopenid
msgtype	メッセージタイプ、ここでは'voice'
voice[media_id]	マルチメディアメッセージID

動画メッセージの送信

パラメータ	説明
touser	顧客のopenid
msgtype	メッセージタイプ、ここでは'video'
video[media_id]	マルチメディアメッセージID

ニュース（記事）メッセージの送信

パラメータ	説明
touser	顧客のopenid
msgtype	メッセージタイプ、ここでは'news'
news[articles]	ニュースメッセージの内容、配列です

articlesの詳細

パラメータ	説明
title	タイトル
description	説明
url	外部リンクアドレス
picurl	画像アドレス

戻り値

詳細はWeChat開発者ドキュメント-カスタマーサービスメッセージ-カスタマーサービスインターフェース.メッセージ送信の戻り値をご覧ください。

シミュレーションミドルウェアは、WeChatサーバーからの戻り値をそのままUDESKシステムに転送する必要があります。UDESKシステムはこの戻り値に基づいてメッセージの送信が成功したかどうかを判断します。

例

# 呼び出し例、テキストメッセージの場合
# Content-Type : application/x-www-form-urlencoded
curl www.simulate_weixin.com -d 'touser=o2IGD0a1OvYAEBfPRa8t34Wc2nUo&msgtype=text&text[content]=123'

3. マルチメディアファイルのアップロード

UDESKシステムがマルチメディアファイルをアップロードし、シミュレーションミドルウェアはWeChatサーバーの新增临时素材インターフェースをリクエストし、WeChatサーバーからの戻り値をそのままUDESKシステムに転送します。

シミュレーションミドルウェアがWeChatサーバーにファイルをアップロードする方法の詳細は、WeChat開発者ドキュメント-素材管理-一時素材の追加をご覧ください。

発信元	受信先	リクエスト方法
UDESKシステム	シミュレーションミドルウェア	POST
#### リクエスト説明

POST 'お客様が入力したシミュレートドメインアドレス?type=TYPE'

リクエストパラメータ

パラメータ	説明
type	ファイルタイプ、image/voice/video
media	値はファイルストリーム

戻り値

詳細は微信開発者ドキュメント-素材管理-一時素材の追加の戻り値を参照してください。

例

# 呼び出し例（curlコマンドを使用し、FORMフォーム方式でマルチメディアファイルをアップロード）:
# Content-Type: multipart/form-data
curl -F media=@test.jpg "www.simulate_weixin.com?type=TYPE"

4. マルチメディアファイルの取得

UDESKシステムがマルチメディアファイルを取得する際、シミュレートミドルウェアが微信サーバーの获取临时素材インターフェースにリクエストし、微信サーバーの戻り値をUDESKシステムに透過的に転送します。

シミュレートミドルウェアが微信サーバーにファイル取得をリクエストする方法の詳細は、微信開発者ドキュメント-素材管理-一時素材の取得を参照してください。

発信元	受信先	リクエスト方式
UDESKシステム	シミュレートミドルウェア	GET

リクエスト説明

GET 'お客様が入力したシミュレートドメインアドレス?media_id=MEDIA_ID&access_token=ACCESS_TOKEN'

リクエストパラメータ

パラメータ	説明
access_token	仮想のaccess_token
media_id	微信サーバー内のメディアファイルID

戻り値

詳細は微信開発者ドキュメント-素材管理-一時素材の取得の戻り値を参照してください。

例

# 呼び出し例
curl www.simulate_weixin.com?media_id=abc&access_token=123

備考

なぜUDESKシステムはマルチメディアファイルをアップロードおよび取得する必要があるのですか？

メッセージの送受信時、画像、音声などのマルチメディアメッセージの取得や呼び出しなどの操作は、微信内部のmedia_idを通じて行われます。
画像、音声などのメッセージを送信する際は、ファイル内容を微信サーバーにアップロードしてmedia_idを取得する必要があります。
画像、音声などのメッセージを受信した際は、微信サーバーに実際のファイル内容を取得する必要があります。

5. 顧客のアバターとニックネームの取得

UDESKシステムが顧客のアバターとニックネームを取得する必要がある場合、UDESKシステムはシミュレートミドルウェアにリクエストし、シミュレートミドルウェアは微信サーバーの获取用户基本信息インターフェースにリクエストし、微信サーバーの戻り値をUDESKシステムに転送します。

シミュレートミドルウェアが微信サーバーに顧客基本情報をリクエストする方法の詳細は、微信開発者ドキュメント-ユーザー管理-ユーザー基本情報の取得(UnionIDメカニズム)を参照してください。

発信元	受信先	リクエスト方式
UDESKシステム	シミュレートミドルウェア	GET

リクエスト説明

GET 'お客様が入力したシミュレートドメインアドレス?openid=OPEN_ID&lang=zh_CN'

リクエストパラメータ

パラメータ名	備考
openid	顧客のopenid
lang	返される国・地域と言語バージョン、現在はzh_CN（簡体字中国語）のみサポート

戻り値

シミュレートミドルウェアは微信サーバーから返された情報をUDESKシステムに透過的に転送します。

詳細は微信開発者ドキュメント-ユーザー管理-ユーザー基本情報の取得(UnionIDメカニズム)を参照してください。

サンプル

# リクエスト例
curl 'www.simulate_weixin.com?openid=o-NbF1HPuegFK5sa1psr7EEeSTSg&lang=zh_CN'

備考

UDESKシステムは、nickname内の特殊文字を削除します。

6. テンプレートメッセージの取得

UDESKシステムがテンプレートメッセージを取得する必要がある場合、UDESKシステムはシミュレーションミドルウェアにリクエストを送信します。シミュレーションミドルウェアはWeChatサーバーの获取模板列表インターフェースにリクエストを送信し、WeChatサーバーからの返り値をUDESKシステムに渡します。

シミュレーションミドルウェアがWeChatサーバーからテンプレートメッセージを取得する方法の詳細については、WeChat開発者ドキュメント-メッセージ管理-テンプレートリストの取得を参照してください。

発信元	受信先	リクエスト方法
UDESKシステム	シミュレーションミドルウェア	GET

リクエスト説明

GET '顧客が入力したシミュレーションドメインアドレス/template/get_all_private_template'

リクエストパラメータ

なし

戻り値

シミュレーションミドルウェアは、WeChatサーバーから返された情報をそのままUDESKシステムに転送します。

詳細については、WeChat開発者ドキュメント-メッセージ管理-テンプレートリストの取得を参照してください。

サンプル

# リクエスト例
curl 'www.simulate_weixin.com/template/get_all_private_template'

# レスポンス例
{
  "template_list": [
    {
      "template_id": "iPk5sOIt5X_flOVKn5GrTFpncEYTojx6ddbt8WYoV5s",
      "title": "賞金受取リマインダー",
      "primary_industry": "ITテクノロジー",
      "deputy_industry": "インターネット|Eコマース",
      "content": "{ {result.DATA} }\n\n受取金額:{ {withdrawMoney.DATA} }\n受取時間:    { {withdrawTime.DATA} }\n銀行情報:{ {cardInfo.DATA} }\n着金時間:  { {arrivedTime.DATA} }\n{ {remark.DATA} }",
      "example": "賞金受取申請を送信しました\n\n受取金額：xxxx元\n受取時間：2013-10-10 12:22:22\n銀行情報：xx銀行(末尾xxxx)\n着金時間：xxxxxxx予定\n\nxxxxにご指定の銀行カードに着金する見込みです"
    }
  ]
}

7. テンプレートメッセージの送信

UDESKシステムがテンプレートメッセージを送信する必要がある場合、UDESKシステムはシミュレーションミドルウェアにリクエストを送信します。シミュレーションミドルウェアはWeChatサーバーの发送模板列表インターフェースにリクエストを送信し、WeChatサーバーからの返り値をUDESKシステムに渡します。

シミュレーションミドルウェアがWeChatサーバーにテンプレートメッセージを送信する方法の詳細については、WeChat開発者ドキュメント-メッセージ管理-テンプレートリストの送信を参照してください。

発信元	受信先	リクエスト方法
UDESKシステム	シミュレーションミドルウェア	POST

リクエスト説明

POST '顧客が入力したシミュレーションドメインアドレス/message/template/send'

リクエストパラメータ

詳細は微信開発者ドキュメント-メッセージ管理-テンプレートメッセージ送信をご参照ください。

{
  "touser": "OPENID",
  "template_id": "ngqIpbwh8bUfcSsECmogfXcV14J0tQlEpBO27izEYtY",
  "url": "http://weixin.qq.com/download",
  "miniprogram": {
    "appid": "xiaochengxuappid12345",
    "pagepath": "index?foo=bar"
  },
  "data": {
    "first": {
      "value": "ご購入おめでとうございます！",
      "color": "#173177"
    },
    "keyword1": {
      "value": "チョコレート",
      "color": "#173177"
    },
    "keyword2": {
      "value": "39.8元",
      "color": "#173177"
    },
    "keyword3": {
      "value": "2014年9月22日",
      "color": "#173177"
    },
    "remark": {
      "value": "またのご利用をお待ちしております！",
      "color": "#173177"
    }
  }
}

戻り値

シミュレーションミドルウェアは、WeChatサーバーから返された情報をUDESKシステムに透過的に転送します。

詳細は微信開発者ドキュメント-メッセージ管理-テンプレートメッセージ送信をご参照ください。

{
  "errcode":0,
  "errmsg":"ok",
  "msgid":200228332
}

例

# リクエスト例
curl 'www.simulate_weixin.com/message/template/get_all_private_template' -d '
  {
    "touser": "OPENID",
    "template_id": "ngqIpbwh8bUfcSsECmogfXcV14J0tQlEpBO27izEYtY",
    "url": "http://weixin.qq.com/download",
    "miniprogram": {
      "appid": "xiaochengxuappid12345",
      "pagepath": "index?foo=bar"
    },
    "data": {
      "first": {
        "value": "ご購入おめでとうございます！",
        "color": "#173177"
      },
      "keyword1": {
        "value": "チョコレート",
        "color": "#173177"
      },
      "keyword2": {
        "value": "39.8元",
        "color": "#173177"
      },
      "keyword3": {
        "value": "2014年9月22日",
        "color": "#173177"
      },
      "remark": {
        "value": "またのご利用をお待ちしております！",
        "color": "#173177"
      }
    }
  }'

# レスポンス例
{
  "errcode":0,
  "errmsg":"ok",
  "msgid":200228332
}

8. access_tokenの取得

UDESKシステムは直接WeChatサーバーとやり取りせず、access_tokenは不要です。

ミドルウェアをシミュレートしてWeChatからaccess_tokenを取得する方法については、WeChat開発者ドキュメント-開発開始-Access tokenの取得をご覧ください。

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search

基本情報

1. メッセージ受信

リクエスト仕様

リクエストパラメータ

戻り値

例

2. メッセージのプッシュ

リクエスト説明

リクエストパラメータ

戻り値

例

3. マルチメディアファイルのアップロード

リクエストパラメータ

戻り値

例

4. マルチメディアファイルの取得

リクエスト説明

リクエストパラメータ

戻り値

例

備考

5. 顧客のアバターとニックネームの取得

リクエスト説明

リクエストパラメータ

戻り値

サンプル

6. テンプレートメッセージの取得

リクエスト説明

リクエストパラメータ

戻り値

サンプル

7. テンプレートメッセージの送信

リクエスト説明

リクエストパラメータ

戻り値

例

8. access_tokenの取得

文档反馈