# 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](/assets/wechat_text.f3341f10934cff9df998049b0eb5ea6102d8d270f0db8b16e69927196e0d9aa4.5b7624f8.png)

The code to send a text message for this channel doesn't differ from the generic message and can be viewed [here](/docs/conversation/message-types/text-message).

### Media Messages

WeChat channel natively supports various types of media messages.

- Image formats: jpeg, jpg, png, gif 
Max image file size: 10MB
![png](/assets/wechat_image.dda61836b724b6aba193bb49050f53de30ba1bd9eb75f9dcc03b3a7a821c41cd.5b7624f8.png)
- Video formats: mp4 
Max video file size: 10MB 
![mp4](/assets/wechat_video.e920e2f0a79e3efd3944af5e5bf3a4ae5e3626f1f9d5a6a3b84ff00776a001ce.5b7624f8.png)
- Audio formats: mp3/amr 
Max audio file size: 2MB 
Max audio duration: 60s
![m4a](/assets/wechat_audio.07eab8f22f44dd0a831f848c393012b58d716fbe9184a8dcb61a46e31227f3f6.5b7624f8.png)


The code to send a media message for this channel doesn't differ from the generic message and can be viewed [here](/docs/conversation/message-types/media-message).

### 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](/assets/wechat_choice.62d8adddd1fa73d33f73f0c8b9eb357b25a5eeca13cbafb56909de9dc86ea946.5b7624f8.png)
- 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](/assets/wechat_card.954e427d2b1cb4db2c68505a0783d2935baaf8fd168ecb2b8f9ff5e9fd5ede91.5b7624f8.png)


The code to send a choice message for this channel doesn't differ from the generic message and can be viewed [here](/docs/conversation/message-types/choice-message).

### 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](/assets/wechat_choice.62d8adddd1fa73d33f73f0c8b9eb357b25a5eeca13cbafb56909de9dc86ea946.5b7624f8.png)
- 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](/assets/wechat_card.954e427d2b1cb4db2c68505a0783d2935baaf8fd168ecb2b8f9ff5e9fd5ede91.5b7624f8.png)


The code to send a card message for this channel doesn't differ from the generic message and can be viewed [here](/docs/conversation/message-types/card-message).

### 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](/assets/wechat_choice.62d8adddd1fa73d33f73f0c8b9eb357b25a5eeca13cbafb56909de9dc86ea946.5b7624f8.png)
- 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](/assets/wechat_carousel.327cd4624e94a460ccb806ee2fdc857d4d6715602a7b1dcf36c42ddead0ca830.5b7624f8.png)


The code to send a carousel message for this channel doesn't differ from the generic message and can be viewed [here](/docs/conversation/message-types/carousel-message).

### 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](https://api.map.baidu.com/lbsapi/getpoint/index.html).

![Location Message](/assets/wechat_location.3d903f1e3ff17ac36cb6b69c888f82f6302bfb818590f6ad746ada7786f4cd78.5b7624f8.png)

![Map](/assets/wechat_map.88c4e463670807f681a02f18f68e9805336e31b82b6a9807f680db9c95d58ff8.5b7624f8.png)

The code to send a location message for this channel doesn't differ from the generic message and can be viewed [here](/docs/conversation/message-types/location-message).

### 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](/assets/wechat_template_preview.7603857364b01a4ba263f122aa17900c39ca5e552f7b3169fc2b3a637bee8943.5b7624f8.jpg)

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.


```json

{
  "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](/assets/wechat_template.22436f84743be8d7c6887ffa20afb1a66b4d10d968fc6d1ca4517d753581ab87.5b7624f8.png)

## Receiving Messages

The WeChat channel supports various kinds of MO messages - text, media, postback.

Note:
Please note that the media URLs included in the contact messages are valid for 7 days.
After that the media is deleted from Conversation API storage.

All of these are delivered by Conversation API via a `POST` to the `MESSAGE_INBOUND` webhook:

Example text MO:


```json
{
  "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:


```json
{
  "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:


```json
{
  "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:


```json
{
  "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`:


```json
{
  "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`:


```json
{
  "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.


```json
{
  "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.


```json
{
  "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:


```json
{
  "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": ""
}
```