Contact form

Props and behavior for MedianContactForm, plus useMedianContact and sendMedianContact for a form of your own.

import { MedianContactForm } from "@mediansh/widget";

<MedianContactForm apiKey="median_pk_..." />;

The form sends the same message the support widget would. The agent answers first, and your team can take over in the inbox. Mounted alongside MedianSupport, the two share a visitor, so a person who writes here and later opens the widget finds the same thread.

Props

MedianUser, telemetry, diagnostics and appState work as they do on MedianSupport. See Context and diagnostics.

Fields

Email and message are always on the form. Add the rest with fields:

<MedianContactForm
  apiKey="median_pk_..."
  fields={[
    { name: "name", label: "Name", required: true },
    { name: "company", label: "Company" },
    {
      name: "topic",
      label: "Topic",
      type: "select",
      options: ["Billing", "A bug", "Something else"],
    },
  ]}
/>;

Validation

The form checks its fields when Send message is pressed, not while the visitor types. Each problem shows under its field, and the first one takes focus. A message clears as soon as the visitor edits that field.

Enter in a one line field sends the form. Cmd+Enter or Ctrl+Enter sends from a paragraph field.

After sending

• Send message shows a spinner while the message is on its way.
• On success the card shows Message sent, a line such as “Replies go to ada@example.com.” with the address given, and a Send another button. The card keeps the form’s height.
• Send another brings the form back with the email and name filled in and the other fields empty.
• On failure the reason shows above the button and every answer stays.
• The email is saved in the browser. MedianSupport on the same site will not ask for it again, and the form fills it in next time.

The form fills the width of its container and has no width of its own.

A “Powered by Median” line sits beside the button and under the thank-you. Hide it with Show Median branding in Settings → Billing, on a plan that allows it. See Plans.

What your team sees

The form’s answers become one message:

Company: Acme
Topic: Billing

We were charged twice for May. Order 4821.

• If this browser has an open widget conversation, the message joins it. Otherwise it starts a new Live chat conversation in the inbox. A resolved conversation is never reopened.
• The email and the name go on the customer record. Typed values win over user.
• With telemetry on, the page URL and browser context come with it. So do diagnostics and data queued with attach(), when you use them.
• The page URL is kept only when the message starts a new conversation.
• The agent and your team reply in the thread. The visitor sees the replies when they open MedianSupport in the same browser.

The copy goes out 2 minutes after a reply the visitor has not seen. If they later open the support panel on your site, the panel decides instead, the same as for any widget visitor.

Limits

Your own form

useMedianContact is the same send without the markup:

import { useMedianContact } from "@mediansh/widget";
import { useState } from "react";

function ContactPage() {
  const contact = useMedianContact({ apiKey: "median_pk_..." });
  const [email, setEmail] = useState("");
  const [message, setMessage] = useState("");

  return (
    <form
      onSubmit={async (event) => {
        event.preventDefault();
        await contact.send({ email, message }).catch(() => {});
      }}
    >
      <input value={email} onChange={(e) => setEmail(e.target.value)} />
      <textarea value={message} onChange={(e) => setMessage(e.target.value)} />
      {contact.error && <p>{contact.error}</p>}
      <button disabled={!contact.isReady || contact.isSending}>Send</button>
    </form>
  );
}

It takes apiKey or identity, plus user, telemetry, diagnostics and appState, as the component does. It needs no provider and no other component on the page.

send does not check the email or the message. Validate in your form. It fails before sending with these messages:

The message

send and sendMedianContact take a MedianContactMessage:

Without React

sendMedianContact is the same send as a plain function:

import { sendMedianContact } from "@mediansh/widget";

form.addEventListener("submit", async (event) => {
  event.preventDefault();
  try {
    await sendMedianContact(
      { apiKey: "median_pk_..." },
      {
        email: email.value,
        message: message.value,
        fields: { Topic: topic.value },
      },
    );
  } catch (error) {
    notice.textContent = error.message;
  }
});

• It takes no identity, diagnostics or appState. Use the hook for those.
• It does not check the email or the message.
• Called on the server, it throws “sendMedianContact() was called where there is no browser, so nothing was sent. Call it from the page, after it has loaded.”

Both the hook and the function save the email in the browser after a successful send.

To render the ready-made form on a page without React, use mountMedianContactForm with a target. See Without React.

Troubleshooting