WeChat channel message support

The WeChat channel of the Conversation API supports a variety of message types.

Message Types

There are generally two types of messages sent and received in WeChat: Free-form, ordinary messages and structured template messages. Ordinary messages can only be sent within 48 hours after a users' last message has been received, and up to 20 ordinary messages can be sent to the same user in this period. Template messages don't have this restriction.

Sending Messages

Some rich messages are natively supported by the WeChat channel, while others must be converted. The following sections demonstrate the mapping between the Conversation API generic message format and the way WeChat renders the messages on mobile devices.

Text Messages

WeChat channel natively supports text messages.

Text Message

The code to send a text message for this channel doesn't differ from the generic message and can be viewed here.

Media Messages

WeChat channel natively supports various types of media messages.

  • Image formats: jpeg, jpg, png, gif
    Max image file size: 10MB
    png
  • Video formats: mp4
    Max video file size: 10MB
    mp4
  • Audio formats: mp3/amr
    Max audio file size: 2MB
    Max audio duration: 60s
    m4a

The code to send a media message for this channel doesn't differ from the generic message and can be viewed here.

Choice Messages

The WeChat channel doesn't natively support Choice messages. The following transcoding rules are applied to Conversation Choice Messages, so they can be delivered on the WeChat channel.

  • Text Choices: Converted to WeChat clickable links. Clicking the link will send invisible postback_data back to the Conversation Callback URL. WeChat will also show the link label in the chat Window.

    Text Choices

  • Call Choices: Converted to text after removing special characters from phone numbers. The WeChat app will make a choice clickable if it detects a valid phone number in the message. Clicking the phone number will display options such as Make Call, Send Message, etc.
  • Location Choice: Converted to Map URL. Refer to Location Message type for more details.
  • URL Choice: Converted to normal URL, opened by embedded browser.

    Choices

The code to send a choice message for this channel doesn't differ from the generic message and can be viewed here.

Card Messages

WeChat channel doesn't natively support Card messages. The following transcoding rules are applied to Conversation Card Messages so they can be delivered on the WeChat channel.

  • Title: Converted to WeChat text.
  • Description: Converted to WeChat text.
  • Media: Converted to WeChat clickable links. Clicking the link will open media content.
  • Text Choices: Converted to WeChat clickable links. Clicking the link will send invisible postback_data back to the Conversation Callback URL. WeChat will also show link label in the chat Window.

    Text Choices

  • Call Choices: Converted to text after removing special characters from phone numbers. The WeChat app will make a choice clickable if it detects a valid phone number in the message. Clicking the phone number will display options such as Make Call, Send Message, etc.
  • Location Choice: Converted to Map URL. Refer to Location Message type for more details.
  • URL Choice: Converted to normal URL.

    Choices

The code to send a card message for this channel doesn't differ from the generic message and can be viewed here.

Carousel Messages

The WeChat channel doesn't natively support Carousel messages. The following transcoding rules are applied to Conversation Carousel messages so they can be delivered on the WeChat channel.

All Cards are joined as a single message. For each card

  • Title: Converted to WeChat text.
  • Description: Converted to WeChat text.
  • Media: Converted to WeChat clickable links. Clicking the link will open media content.
  • Text Choices: Converted to WeChat clickable links. Clicking the link will send invisible postback_data back to the Conversation Callback URL. WeChat will also show link label in the chat Window.

    Text Choices

  • Call Choices: Converted to text after removed special characters from phone numbers. WeChat app will make a choice clickable if it detects valid phone number in the message. Clicking the phone number will display options such as Make Call, Send Message, etc.
  • Location Choice: Converted to Map URL. Refer to Location Message type for more details.
  • URL Choice: Converted to normal URL.

    Choices

The code to send a carousel message for this channel doesn't differ from the generic message and can be viewed here.

Location Messages

WeChat channel doesn't natively support location messages. Location messages or location choices sent to WeChat will be converted to a Map URL. Clicking the URL will open the map within embedded browser.

Due to the restrictions on geographic data in China, the raw GPS data in WGS84 format (used by many Map Service Providers, such as Google) can't be used in China. Instead, local Chinese Map Service Providers use different geographic data formats, such as BD09.

To send a location message or location choice to WeChat, you need to have location data in BD09 format. Please get coordinates from a Chinese Map Service Provider such as Baidu Map.

Location Message

Map

The code to send a location message for this channel doesn't differ from the generic message and can be viewed here.

Template Messages

The format of template messages is defined by WeChat. Customers go to the Template Library section in their WeChat Admin portal, choose the templates that fit their use cases, and add those templates to their account. Each added template will be assigned a unique template ID and available variables.

Template preview

To send Template messages on the WeChat channel, use template_message and populate the appropriate values. Each parameter has 2 attributes to set: value and color. The value attribute is required, The color attribute is optional.

Copy
Copied
{
  "app_id": "{{APP}}",
  "recipient": {
    "contact_id": "{{WECHAT_CONTACT}}"
  },
  "message": {
    "template_message": {
      "channel_template": {
        "WECHAT": {
          "template_id": "your-unique-template-id",
          "parameters": {
            "first.value":"Transaction Alert",
            "first.color": "#173177",
            "accountType.value":"VISA",
            "account.value": "Ending with 1234",
            "pay.value": "$57.56",
            "address.value": "Food Delivery",
            "time.value": "6:27pm (SGT) Nov 1 2021",
            "remark.value": "If you didn't make this request, contact immediately: +6512345678",
            "remark.color": "#173177"
          }
        }
      }
    }
  }
}

Template message

Receiving Messages

The WeChat channel supports various kinds of MO messages - text, media, postback. All of these are delivered by Conversation API via a POST to the MESSAGE_INBOUND webhook:

Example text MO:

Copy
Copied
{
  "app_id": "01F6PDXVY6Z5GT0AM1YPABCDEFG",
  "accepted_time": "2021-11-11T07:39:35.773669Z",
  "event_time": "2021-11-11T07:39:34.122Z",
  "project_id": "60d53e51-21f2-abcd-1234-a2d127f480c0",
  "message": {
    "id": "01FM6Z039AN154JA6Q9FABCDEFG",
    "direction": "TO_APP",
    "contact_message": {
      "text_message": {
        "text": "Text MO"
      }
    },
    "channel_identity": {
      "channel": "WECHAT",
      "identity": "oA4ha12Pp-abcDeFgHiJ12-LHrdg",
      "app_id": "01F6PDXVY6Z5GT0AM1YABCDEFG"
    },
    "conversation_id": "01FHZFQF598ZX723CHRW123456",
    "contact_id": "01FHZFNK0R9FG8WJK7SABCDEFG",
    "metadata": "",
    "accept_time": "2021-11-11T07:39:35.710185Z",
    "sender_id": ""
  },
  "message_metadata": ""
}

Example location MO:

Copy
Copied
{
  "app_id": "01F6PDXVY6Z5GT0AM1YPABCDEFG",
  "accepted_time": "2021-11-11T07:41:38.368424Z",
  "event_time": "2021-11-11T07:41:36.974Z",
  "project_id": "60d53e51-21f2-abcd-1234-a2d127f480c0",
  "message": {
    "id": "01FM6Z3V02ZAEW7RF8D6ABCDEFG",
    "direction": "TO_APP",
    "contact_message": {
      "location_message": {
        "title": "HarbourFront Tower 2",
        "coordinates": {
          "latitude": 1.2646714,
          "longitude": 103.818726
        },
        "label": "3 HarbourFront Place 099254 Singapore"
      }
    },
    "channel_identity": {
      "channel": "WECHAT",
      "identity": "oA4ha12Pp-abcDeFgHiJ12-LHrdg",
      "app_id": "01F6PDXVY6Z5GT0AM1YABCDEFG"
    },
    "conversation_id": "01FHZFQF598ZX723CHRWABCDEFG",
    "contact_id": "01FHZFNK0R9FG8WJK7S9123456",
    "metadata": "",
    "accept_time": "2021-11-11T07:41:38.304523Z",
    "sender_id": ""
  },
  "message_metadata": ""
}

Example media MO:

Copy
Copied
{
  "app_id": "01F6PDXVY6Z5GT0AM1YABCDEFG",
  "accepted_time": "2021-11-11T07:43:09.275936Z",
  "event_time": "2021-11-11T07:43:05.789Z",
  "project_id": "60d53e51-21f2-abcd-1234-a2d127f480c0",
  "message": {
    "id": "01FM6Z6KRTNB4XBYAPV6ABCDEFG",
    "direction": "TO_APP",
    "contact_message": {
      "media_message": {
        "url": "https://convapi-eu1tst.s3.eu-west-1.amazonaws.com/01F6PDXVY6Z5GT0AM1YABCDEFG/01FM6Z6KDK5NP01FHQG123456.jpg",
        "thumbnail_url": ""
      }
    },
    "channel_identity": {
      "channel": "WECHAT",
      "identity": "oA4ha12Pp-abcDeFgHiJ12-LHrdg",
      "app_id": "01F6PDXVY6Z5GT0AM1YABCDEFG"
    },
    "conversation_id": "01FHZFQF598ZX723CABCDEFG",
    "contact_id": "01FHZFNK0R9FG8WJK7SABCDEFG",
    "metadata": "",
    "accept_time": "2021-11-11T07:43:09.211687Z",
    "sender_id": ""
  },
  "message_metadata": ""
}

Example choice response message:

Copy
Copied
{
  "app_id": "01F6PDXVY6Z5GT0AM1YPABCDEFG",
  "accepted_time": "2021-11-11T07:49:00.175682Z",
  "event_time": "2021-11-11T07:48:59.097Z",
  "project_id": "60d53e51-21f2-abcd-1234-a2d127f480c0",
  "message": {
    "id": "01FM6ZHAH5WYS4JN5JYPABCDEFG",
    "direction": "TO_APP",
    "contact_message": {
      "choice_response_message": {
        "message_id": "01FM6ZGXT36AMA0QBB9ABCDEFG",
        "postback_data": "movieId=1234&actionId=101"
      }
    },
    "channel_identity": {
      "channel": "WECHAT",
      "identity": "oA4ha12Pp-abcDeFgHiJ12-LHrdg",
      "app_id": "01F6PDXVY6Z5GT0AM1YPABCDEFG"
    },
    "conversation_id": "01FHZFQF598ZX723CHRWABCDEFG",
    "contact_id": "01FHZFNK0R9FG8WJK7S9ABCDEFG",
    "metadata": "",
    "accept_time": "2021-11-11T07:49:00.105016Z",
    "sender_id": ""
  },
  "message_metadata": ""
}

Receiving Status

WeChat only provides a delivery status for template messages. The positive status of a template message delivered on the WeChat channel will be DELIVERED:

Copy
Copied
{
  "app_id": "01F6PDXVY6Z5GT0AM1YPABCDEFG",
  "accepted_time": "2021-11-11T07:48:47.043Z",
  "event_time": "2021-11-11T07:48:47.851947Z",
  "project_id": "60d53e51-21f2-abcd-1234-a2d127f480c0",
  "message_delivery_report": {
    "message_id": "01FM6ZGXT36AMA0QBB9VABCDEFG",
    "conversation_id": "01FHZFQF598ZX723CHRABCDEFG",
    "status": "DELIVERED",
    "channel_identity": {
      "channel": "WECHAT",
      "identity": "oA4ha12Pp-abcDeFgHiJ12-LHrdg",
      "app_id": "01F6PDXVY6Z5GT0AM1YABCDEFG"
    },
    "contact_id": "01FHZFNK0R9FG8WJK7SABCDEFG",
    "metadata": ""
  },
  "message_metadata": ""
}

The positive status of an ordinary message delivery will be QUEUED_ON_CHANNEL:

Copy
Copied
{
  "app_id": "01F6PDXVY6Z5GT0AM1YPABCDEFG",
  "accepted_time": "2021-11-11T07:48:47.043Z",
  "event_time": "2021-11-11T07:48:47.851947Z",
  "project_id": "60d53e51-21f2-abcd-1234-a2d127f480c0",
  "message_delivery_report": {
    "message_id": "01FM6ZGXT36AMA0QBB9VABCDEFG",
    "conversation_id": "01FHZFQF598ZX723CHRABCDEFG",
    "status": "QUEUED_ON_CHANNEL",
    "channel_identity": {
      "channel": "WECHAT",
      "identity": "oA4ha12Pp-abcDeFgHiJ12-LHrdg",
      "app_id": "01F6PDXVY6Z5GT0AM1YABCDEFG"
    },
    "contact_id": "01FHZFNK0R9FG8WJK7SABCDEFG",
    "metadata": ""
  },
  "message_metadata": ""
}

If the status is FAILED, the reason will include more information about the failure.

Copy
Copied
{
  "app_id": "01F6PDXVY6Z5GT0AM1YABCDEFG",
  "accepted_time": "2021-11-11T07:53:20.777Z",
  "event_time": "2021-11-11T07:53:21.143671Z",
  "project_id": "60d53e51-21f2-abcd-1234-a2d127f480c0",
  "message_delivery_report": {
    "message_id": "01FM6ZS949X61P607KA1BACDEFG",
    "conversation_id": "01FHZFQF598ZX723CHRWABCDEFG",
    "status": "FAILED",
    "channel_identity": {
      "channel": "WECHAT",
      "identity": "oA4ha12Pp-abcDeFgHiJ12-LHrdg",
      "app_id": "01F6PDXVY6Z5GT0AM1YABCDEFG"
    },
    "contact_id": "01FHZFNK0R9FG8WJK7ABCDEFG",
    "reason": {
      "code": "MEDIA_NOT_REACHABLE",
      "description": "The provided media [https://www.url.com/samples/picture.jpg] could not be reached: [Not Found]",
      "sub_code": "UNSPECIFIED_SUB_CODE"
    },
    "metadata": ""
  },
  "message_metadata": ""
}

Block Channel

It's possible for users to block a WeChat channel by using the "Unfollow" feature from their WeChat App. When this happens, an opt_out_notification will be sent to the app's callback webhook and customers can take action, such as removing their contact_id from their user list.

Copy
Copied
{
  "app_id": "01F6PDXVY6Z5GT0AM1YABCDEFG",
  "accepted_time": "2021-11-11T07:55:09.201036Z",
  "event_time": "2021-11-11T07:55:08.188Z",
  "project_id": "60d53e51-21f2-abcd-1234-a2d127f480c0",
  "opt_out_notification": {
    "contact_id": "01FHZFNK0R9FG8WJK7ABCDEFG",
    "channel": "WECHAT",
    "identity": "oA4ha12Pp-abcDeFgHiJ12-LHrdg",
    "status": "OPT_OUT_SUCCEEDED",
    "request_id": "01FM6ZWK0PZBZBX64G8ABCDEFG"
  },
  "message_metadata": ""
}

Unblock Channel

Users can unblock/follow WeChat channel at any time. If they do so, an opt_in_notification will be sent to app's callback webhook. For example:

Copy
Copied
{
  "app_id": "01F6PDXVY6Z5GT0AM1YABCDEFG",
  "accepted_time": "2021-11-11T07:58:36.699110Z",
  "event_time": "2021-11-11T07:58:35.419Z",
  "project_id": "60d53e51-21f2-abcd-1234-a2d127f480c0",
  "opt_in_notification": {
    "contact_id": "01FHZFNK0R9FG8WJK7ABCDEFG",
    "channel": "WECHAT",
    "identity": "oA4ha12Pp-abcDeFgHiJ12-LHrdg",
    "status": "OPT_IN_SUCCEEDED",
    "request_id": "01FM6ZWK0PZBZBX64G8ABCDEFG"
  },
  "message_metadata": ""
}
Was this page helpful?
SecurityPrivacyLegal & ComplianceCookie Statement
© 2022 Sinch. All rights reserved.